FEATURE: Unified JSON Projection API #3853
Description
Description
Provide a consistent way of filtering JSON output. This API allows developers to define exactly which fields of a Java object should be serialized, supporting both simple flat structures and deep nested graphs.
The API is designed to be library-agnostic, allowing the same projection definition to work across different JSON providers without requiring changes to domain models or POJOs.
Core Features
Flexible Syntax: Supports Dot-notation (address.city) and Avaje/LinkedIn-style grouping (address(city, zip)).
Type-Safety: Full support for Java method references (User::getName) to provide refactor-safe projections.
Hierarchical Validation: Projections are validated against the target class hierarchy at definition time, including support for unwrapping Collections and Maps.
Fluent & Declarative API: A Projected wrapper for programmatic use and a @Project annotation for MVC controllers.
Example Usage
- Programmatic (Script API):
get("/user/{id}", ctx -> {
User user = service.find(ctx.path("id").value());
return Projected.wrap(user)
.include("id, name")
.include(User::getAddress, addr -> addr.include("city"));
});- Declarative (MVC API):
@GET
@Project("id, name, address(city)")
public User getUser(String id) {
return service.find(id);
}Core Components
The feature consists of three primary components that work together to define, wrap, and apply the filtering logic.
- Projection
The engine that parses syntax and validates paths against the class hierarchy.
// Manual definition
Projection<User> p = Projection.of(User.class)
.include("id, address(city)");- Projected
// Script API
get("/user", ctx -> {
return Projected.wrap(user).include(User::getName);
});@Project
A declarative annotation for MVC controllers.
// MVC API
@GET
@Project("id, name")
public User getUser() { ... }@kliushnichenko your input is welcome.