ADR-0011: DTO design — complete top-level representations, slim embedded children
Status: Accepted
Date: 2026-06-05
Scope: core (any backend exposing a REST API)
Context
Two recurring DTO temptations corrode an API: trimming fields from a response
because one client doesn’t use them today (breaking the next client), and
embedding full child DTOs inside parent responses (duplicating shared context on
every list item — payment method, category, currency repeated N times on an
invoice with N expenses).
Decision
Top-level DTOs are complete domain representations. Never remove fields
from a top-level response just because a particular client doesn’t currently
use them. REST APIs serve contracts, not individual consumers.
Embedded child lists use a slim, context-specific DTO named <Parent><Child>Response, living in the parent feature’sdto/ package.
It omits exactly the fields the parent already provides.
Create a slim embedded DTO when all three hold:
a parent response embeds a List<SomeFullResponse> whose items contain
nested objects;
those nested objects are identical across items (they come from the parent
context);
the list can grow large.
Response DTOs are constructed from domain entities (constructor mapping,
no mapper classes); request DTOs are records carrying validation annotations.
Frontends mirror the backend DTO names exactly in their shared types, so
a name is a cross-repo search key.
Amendment — 2026-09-10: a collection returns summaries
Decided while building dracomania’s decks. It is recorded here, in core, because the
pattern already runs across the repos without having been written down. Expenses has ConversationSummaryResponse / ConversationDetailResponse and PaymentWebhookEventSummaryResponse / …DetailResponse.
A collection endpoint returns a summary of each item; the full representation lives
at the item’s own endpoint.GET /players/{playerId}/decks returns each deck’s identity,
name and card count. GET /players/{playerId}/decks/{deckId} returns the deck with its
cards. A client that needs all of one item fetches that item.
This is not the trimming the rule above forbids. The summary is a representation
of its own, with its own contract, sized for what a list is for. It is not a full DTO
with fields removed because one client ignores them. The no-trimming rule applies to
each representation separately: neither the summary nor the detail loses a field
because a client doesn’t read it today.
A summary omits what its collection’s context already provides, the same way a
slim embedded child does: a player’s decks don’t repeat the owner id.
Nested resources inside the full representation still use slim embedded DTOs, per
the rule above.
Trigger: use a summary when the full representation carries nested collections or
heavy fields that a list does not render. When a collection’s items are already small
and flat (a set’s card catalogue, which clients fetch whole and cache), return the full
items; there is nothing to summarise.
Naming:<Entity>SummaryResponse for a list item, <Entity>DetailResponse for the
full representation. A project with a recorded naming deviation maps the pair onto its
own scheme. Dracomania uses DeckSummaryDTO / DeckDTO.
Example
Real code from the repos — optional
Agents: safe to skip. The Decision above is the specification; everything below is
illustration. Skipping this block costs you nothing normative and saves tokens. Expand it
when you need the shape rather than the rule — porting the pattern to a new project, or
answering “what does this actually look like”.
The pair the amendment names, as it actually exists.
/** List-item view of a conversation — no messages (used by the conversation rail). */public record ConversationSummaryResponse(UUID id, String title, Instant lastMessageAt) { public ConversationSummaryResponse(Conversation conversation) { this(conversation.getId(), conversation.getTitle(), conversation.getLastMessageAt()); }}
/** Full conversation with its ordered messages (used when opening a thread). */public record ConversationDetailResponse( UUID id, String title, Instant createdAt, Instant lastMessageAt, List<ChatMessageResponse> messages) { public ConversationDetailResponse(Conversation conversation) { this( conversation.getId(), conversation.getTitle(), conversation.getCreatedAt(), conversation.getLastMessageAt(), conversation.getMessages().stream().map(ChatMessageResponse::new).toList() ); }}
GET /chat/conversations returns the summary, GET /chat/conversations/{id} the detail.
The difference is not a trimmed field list — it is messages, the one field a conversation
rail has no use for and that a long thread makes expensive.
Both are records, immutable with value equality for free, and both map from the entity in
a constructor that takes it. The dependency points one way: Conversation knows about
neither, so the domain stays clear of presentation.
The detail expands its children through ChatMessageResponse, which in turn expands each
message’s attachments. That is the full representation doing its job — a caller opening one
thread wants it whole — and it terminates, because a message’s attachments belong to the
message rather than being a resource of their own to follow.
Note what the summary leaves out beyond messages: no createdAt, and no owner. The rail
sorts by lastMessageAt, and the owner is the authenticated user the collection was
already scoped to — a summary omits what its collection’s context provides.