Returning a domain entity from a REST controller couples the API response to the entity’s internal structure. A data transfer object (DTO) avoids that coupling by carrying only the data a consumer needs, without exposing domain behavior or invariants. section 5.2.4 section 5.4.2
A DTO can serve as a read-only projection of domain data. For example, ArticleDTO carries article information for display or transmission; the Article entity remains responsible for behavior and business rules. DTOs at output ports are lightweight and immutable, and are shaped around the port’s needs. section 4.6.3 section 5.2.4
Listing 5.5 DTOs as records
public record NotificationTextDTO(String value) { #A
public NotificationTextDTO {
Objects.requireNonNull(
value, "Notification text must not be null"); #B
}
}
public record ArticleDTO( #C
String id, String title, String authorId, String status) {
}
These Java records show a notification value and an article DTO with only the fields needed across the boundary. section 5.2.4
Output adapters translate port DTOs into infrastructure-specific formats. Repositories are the exception to the DTO-only output-port rule: they can accept and return domain entities to persist or reconstitute state. section 5.5
Repository method names can make the consumer’s intent visible:
- save and delete accept domain entities for writes; read methods return entities for handlers that need to mutate an aggregate. section 5.3.2
- find methods return DTOs or projections for query handlers serving data without loading the full aggregate. section 5.3.2
Mapping is a trade-off between isolation and maintenance. One-way mapping converts a domain entity to a DTO on the way out, protecting the API while leaving persistence coupled to the domain. Two-way mapping separates the persistence entity as well; the repository adapter maps persistence to domain, and the handler maps domain to DTO. Both mappers must stay in sync as the model evolves. section 5.4.3 section 5.4.4
A query that needs domain behavior
A publication-readiness query loads the Article aggregate because the answer depends on domain rules. The handler invokes its read-only assessment and maps the result to a DTO; the controller then maps that DTO to an HTTP response. A simpler data-retrieval query can instead return a DTO directly as a read model. section 5.4.5
Listing 5.15 Full Bridge: Inside the query handler
@ApplicationService
@RequiredArgsConstructor
final class PublicationReadinessHandler
implements PublicationReadinessUseCase {
private final ArticleRepository articleRepository;
private final PublicationReadinessMapper mapper; #A
@Override
public Either<Error, PublicationReadinessDTO>
handle(final PublicationReadinessQuery query) {
return ArticleId.validateThenCreate(query.articleId())
.flatMap(this.articleRepository::readById) #B
.map(Article::assessPublicationReadiness) #C
.map(this.mapper::toDTO); #D
}
}
The handler shows the aggregate read, domain assessment, and DTO mapping in sequence. section 5.4.5
For stronger isolation, a full bridge uses separate request, query, domain, persistence, DTO, and response types. Each boundary has a mapper, allowing models to evolve independently at the cost of more types and mapping work. section 5.4.5









