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.

1. 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)");

2. Projected

// Script API
get("/user", ctx -> {
  return Projected.wrap(user).include(User::getName);
});

3. @Project

A declarative annotation for MVC controllers.

// MVC API
@GET
@Project("id, name")
public User getUser() { ... }

@kliushnichenko your input is welcome.