Mastering @JsonFormat in Spring Boot 3: Advanced Date & Enum Handling

1. Introduction

@JsonFormat is a Jackson annotation that allows fine‑grained control over how Java object fields are serialized and deserialized to JSON, commonly used for dates, times, numbers, and enums. It can transform a Date into a custom string such as "2025-12-31" or an ISO‑8601 timestamp with timezone.

2. Practical Cases

2.1 Date Formatting

By default Spring Boot 3.4.2 returns dates in ISO‑8601 extended format (e.g., 2025-04-26T01:47:11.428+00:00), which may not match the desired yyyy-MM-dd HH:mm:ss pattern and timezone. Two solutions are provided:

Define the format and timezone in application.yml:

spring:
  jackson:
    date-format: yyyy-MM-dd HH:mm:ss
    time-zone: GMT+8

Use the @JsonFormat annotation directly on the field:

@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
private Date createTime = new Date();

2.2 Controlling Format and Automatic Error Repair

Output dates as an array:

@JsonFormat(shape = Shape.ARRAY, timezone = "GMT+8")
private LocalDate date = LocalDate.now();

Enable lenient parsing to automatically correct invalid dates:

@JsonFormat(
  pattern = "yyyy-MM-dd HH:mm:ss",
  timezone = "GMT+8",
  lenient = OptBoolean.TRUE)
private Date createTime = new Date();

2.3 Specifying Locale and Output Type

Customize the locale to produce language‑specific month and period strings:

@JsonFormat(pattern = "yyyy MMMM dd a", locale = "en")
private Date createTime = new Date();

For numeric timestamps, set the shape to NUMBER:

@JsonFormat(shape = Shape.NUMBER, timezone = "GMT+8")
private Date createTime = new Date();

2.4 Case‑Insensitive Deserialization

When incoming JSON keys have inconsistent casing, enable case‑insensitive property handling:

@JsonFormat(
  with = JsonFormat.Feature.ACCEPT_CASE_INSENSITIVE_PROPERTIES)
public class User {}

2.5 Enum Serialization

Define an enum with additional fields:

public enum UserStatus {
  ACTIVE("活跃", 100, true),
  INACTIVE("不活跃", 101, false),
  PENDING("待激活", 102, false);
  private final String description;
  private final int code;
  private final boolean isActive;
  UserStatus(String description, int code, boolean isActive) {
    this.description = description;
    this.code = code;
    this.isActive = isActive;
  }
  public String getDescription() { return description; }
  public int getCode() { return code; }
  public boolean isActive() { return isActive; }
}

Serialize the enum as a JSON object to include all fields:

@JsonFormat(shape = JsonFormat.Shape.OBJECT)
public enum UserStatus {}

Alternatively, configure Jackson to use toString() for enums:

spring:
  jackson:
    serialization:
      write-enums-using-to-string: true

@Override
public String toString() {
  return description + "/" + code + "/" + isActive;
}

3. Supporting Code Samples

Entity and controller examples used throughout the article:

public class User {
  private Long id;
  private String firstName;
  private String lastName;
  private Date createTime = new Date();
  // getters, setters, constructors
}

@RestController
@RequestMapping("/users")
public class UserController {
  @GetMapping("/{id}")
  public ResponseEntity<User> query(@PathVariable Long id) {
    return ResponseEntity.ok(new User(id, "pack", "xg", new Date()));
  }
}

4. Visual Results

Default ISO‑8601 output:

Formatted date using configuration:

Locale‑specific output (English):

Locale‑specific output (Chinese):

Enum serialized as object:

Enum serialized using toString: