Jackson Annotations Cheat Sheet: Every Annotation You Need With Examples

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

@JsonIgnore — Exclude a Field Entirely

Place @JsonIgnore on any field or method you never want included in serialisation or deserialisation output.

public class UserAccount {
    private String username;

    @JsonIgnore    // Never written to or read from JSON
    private String passwordHash;

    // Getters and setters
}

// Serialise
{"username":"alice"}
// passwordHash is absent from the output

@JsonInclude — Skip Null or Empty Fields

@JsonInclude controls whether null, empty, or default-value fields are written to JSON. Apply it at class or field level.

@JsonInclude(JsonInclude.Include.NON_NULL)   // Skip any null field
public class ProductDetails {
    private String productName;
    private String productDescription; // Will be omitted when null
    private Double discountRate;       // Will be omitted when null
    // Getters and setters
}

// productDescription and discountRate are null:
{"productName":"Keyboard"}
// Only non-null fields appear

Other commonly used inclusion values:

NON_EMPTY — also skips empty strings and empty collections.
NON_DEFAULT — skips fields whose value equals the Java default (0, false, null).
ALWAYS (default) — always writes every field.

@JsonFormat — Control Date and Number Formatting

@JsonFormat is most commonly used to control how dates are serialised. Without it, Jackson writes LocalDate as a numeric array by default.

public class InvoiceRecord {
    private Long invoiceId;

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

    @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "#.##")
    private double totalAmount;
    // Getters and setters
}

{"invoiceId":500,"invoiceDate":"2026-04-09","totalAmount":"199.99"}

@JsonAlias — Accept Multiple Input Names

When deserialising from multiple sources that use different key names for the same field, @JsonAlias lets you accept all variants.

public class SearchQuery {
    @JsonAlias({"q", "query", "search_term"})
    private String searchKeyword;
    // Getter and setter
}

All three JSON inputs below deserialise into searchKeyword:

{"q":"jackson"}
{"query":"jackson"}
{"search_term":"jackson"}

@JsonIgnoreProperties — Ignore Unknown Fields at Class Level

Rather than configuring FAIL_ON_UNKNOWN_PROPERTIES globally, you can opt out per class:

@JsonIgnoreProperties(ignoreUnknown = true)
public class ExternalApiResponse {
    private String status;
    private String message;
    // Extra fields in the API response are silently ignored
}

@JsonCreator and @JsonProperty on Constructor Parameters

For immutable classes without setters, annotate a constructor with @JsonCreator and mark each parameter with @JsonProperty so Jackson knows which JSON key maps to which parameter.

public class ImmutablePoint {
    private final double xCoordinate;
    private final double yCoordinate;

    @JsonCreator
    public ImmutablePoint(
        @JsonProperty("x") double xCoordinate,
        @JsonProperty("y") double yCoordinate
    ) {
        this.xCoordinate = xCoordinate;
        this.yCoordinate = yCoordinate;
    }
    // Getters only
}

// Deserialise
{"x":3.5,"y":7.2}  ->  ImmutablePoint(xCoordinate=3.5, yCoordinate=7.2)

Quick-Reference Table

The following table summarises every annotation covered in this guide. Use it as a quick lookup when you need to find the right tool for a specific mapping requirement.

Annotation	Purpose	Applies To
`@JsonProperty`	Rename a field in JSON	Field, method, parameter
`@JsonIgnore`	Exclude field from JSON entirely	Field, method
`@JsonInclude`	Skip nulls / empty / default values	Class, field
`@JsonFormat`	Format dates, numbers	Field, method
`@JsonAlias`	Accept multiple input key names	Field
`@JsonIgnoreProperties`	Ignore unknown fields at class level	Class
`@JsonCreator`	Designate a constructor or factory for deserialisation	Constructor, method
`@JsonTypeInfo`	Add type discriminator for polymorphism	Class
`@JsonSubTypes`	Declare concrete subtypes for polymorphism	Class
`@JsonUnwrapped`	Flatten nested object fields into parent	Field

AI Prompts for Jackson Annotations

Annotate POJO to Match JSON Schema

I have this Java POJO: [paste class here]. The JSON produced must match this target schema: [paste expected JSON here]. Apply the minimum set of Jackson 3 annotations needed — @JsonProperty, @JsonIgnore, @JsonInclude, @JsonFormat — to make the serialised output exactly match the target. Add a one-line comment above each annotation explaining why it is needed and what field-level problem it solves.

What it does: Analyses the gap between your POJO’s field names and the target JSON schema, then applies the precise annotation to each field that closes that gap. Each annotation is followed by an inline comment explaining the exact mapping it enforces, so future readers understand why each annotation is present.

When to use it: When integrating with an external API that uses a different naming convention (e.g. snake_case vs camelCase), requires specific fields to be omitted, or mandates a fixed date format. Run this prompt after you have defined your POJO and have the target JSON schema from the API documentation in hand.

Generate Mix-in for Third-Party Class

I need to control how this third-party class is serialised by Jackson 3 without modifying the class itself: [paste the class or its signature here]. Create a Mix-in annotation class that applies @JsonIgnore to fields I should not expose, renames fields using @JsonProperty, and formats any date fields with @JsonFormat. Then show how to register the Mix-in on a JsonMapper builder instance.

What it does: Produces an abstract Mix-in class whose annotations shadow the target class’s fields, along with the JsonMapper.builder().addMixIn(Target.class, TargetMixin.class).build() registration call. The Mix-in is kept in a separate file so it can be updated independently if the third-party class changes.

When to use it: When consuming a library whose classes you cannot modify — such as a generated SDK or a domain model from another team’s module — but whose JSON representation needs renaming, filtering, or date formatting to match your API contract.

Standardise Date Annotation Formats

I have this Java class with multiple date fields using @JsonFormat: [paste class here]. Audit every @JsonFormat annotation and rewrite each one to use ISO-8601 format — yyyy-MM-dd for date-only fields and yyyy-MM-dd’T’HH:mm:ss for datetime fields. For each change, state the original pattern, the replacement pattern, and a one-sentence reason for the change. Flag any field where the original format carried business-specific meaning that ISO-8601 cannot preserve.

What it does: Audits every @JsonFormat(pattern=...) annotation in the provided class, rewrites each to the appropriate ISO-8601 variant, and flags any edge cases where the original pattern encoded domain-specific formatting that a standard pattern cannot replicate — for example, two-digit year formats or locale-specific separators.

When to use it: When running a consistency audit on a codebase that has grown over several years with mixed date formats added by different developers. Also useful before exposing an API to external consumers who expect standard ISO-8601 dates rather than locale-specific or custom patterns.

Conclusion

Jackson’s annotation set is compact but powerful. For the vast majority of projects, mastering @JsonProperty, @JsonIgnore, @JsonInclude, @JsonFormat, @JsonAlias, and @JsonCreator will cover every mapping scenario you encounter. Keep the quick-reference table bookmarked and reach for custom serialisers only when annotations cannot express what you need.

@ankurm