liveBook · Manning

Data transfer object

As explained in Clean Applications with Hexagonal Architecture

A data transfer object is a data-carrying type designed to convey structured information between software components without encapsulating domain behavior.

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

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Works through repository conventions and mapping strategies, from outbound-only mapping to separate models at every boundary.
Examples
Shows Java record DTOs for notifications and articles, plus a publication-readiness query mapped from domain assessment to HTTP response.
What you can do after
Evaluate mapping strategies for API isolation, persistence separation, and the maintenance cost of additional mappers.
How it connects
Connects DTOs to domain entities, command-query separation, repositories, output ports, adapters, and projections.

Also explained in

Compare how 10 books explain data transfer object →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Clean Applications with Hexagonal Architecture. The section links point to the parts of the book it draws on.