Mastering @JsonView in Spring Boot: Fine-Grained JSON Control for APIs

1. Introduction

RESTful APIs are the standard for front‑back communication, and developers often need to tailor the JSON response structure for different clients, roles, or business scenarios. The Jackson @JsonView annotation offers an elegant and efficient way to achieve this in Spring Boot 2.7.16.

@JsonView allows you to specify which properties of a Java object should be included or excluded during JSON serialization, enabling fine‑grained control without modifying the entity class itself.

By defining multiple views, each representing a specific set of fields, you can apply a view to a controller method to dictate which fields are serialized for that endpoint.

2. Application Scenarios

Control of data exposure levels : Define a basic view for public fields and a full view that includes sensitive data such as passwords or ID numbers, then select the appropriate view per API method.

Role‑based data customization : Use @JsonView together with Spring Security to expose all fields to administrators while limiting regular users to basic information.

API versioning : Assign a distinct view to each API version so older versions omit newly added fields.

Data aggregation and splitting : Combine or separate entity data in a single JSON response by selecting the suitable view.

3. Practical Example

3.1 View Definitions

<code>public interface UserView {
  // Basic information
  public interface Basic {}
  // Excludes password
  public interface WithoutPassword extends Basic {}
  // All information (including sensitive data)
  public interface Full extends Basic {}
}</code>

3.2 Domain Object

<code>public class User {
  @JsonView(UserView.Basic.class)
  private Long id;

  @JsonView(UserView.Basic.class)
  private String username;

  @JsonView(UserView.Full.class)
  private String password;

  @JsonView({UserView.WithoutPassword.class, UserView.Full.class})
  private String idNo;
  // getters and setters
}</code>

3.3 Controller

<code>@RestController
@RequestMapping("/jsonview")
public class JsonViewController {

  @GetMapping("/user/basic")
  @JsonView(UserView.Basic.class)
  public User userBasic() {
    return new User(1L, "pack", "123123", "110101199001014294");
  }

  @GetMapping("/user/nopassword")
  @JsonView(UserView.WithoutPassword.class)
  public User userNoPassword() {
    return new User(1L, "pack", "123123", "110101199001014294");
  }

  @GetMapping("/user/full")
  @JsonView(UserView.Full.class)
  public User userFull() {
    return new User(1L, "pack", "123123", "110101199001014294");
  }
}
</code>

Resulting JSON for the three endpoints is shown in the images below.

3.4 Programmatic Control

If you prefer not to annotate controller methods, you can use MappingJacksonValue to set the view programmatically.

<code>@GetMapping("/user/program")
public MappingJacksonValue program() {
  User user = new User(1L, "pack", "123123", "110101199001014294");
  MappingJacksonValue value = new MappingJacksonValue(user);
  value.setSerializationView(UserView.WithoutPassword.class);
  return value;
}
</code>

Note: The method must return MappingJacksonValue .

3.5 Combining with Other Annotations

You can add @JsonIgnore or @JsonInclude to further refine output. For example, adding an @JsonIgnore field will prevent it from appearing in any view.

<code>@JsonView(UserView.Basic.class)
@JsonIgnore
private String email;
</code>

The email field is not serialized, even when the Basic view is used.

Conclusion

The @JsonView annotation provides a powerful, flexible mechanism for controlling JSON serialization in Spring Boot APIs. By defining views and applying them to fields or controller methods, you can expose different data levels, support role‑based responses, manage API versioning, and combine with other Jackson annotations for precise output control.