Spring Boot DTO Design

Model the transport as an allow-listed, immutable value that exists only at the boundary. The moment a JPA entity or a domain aggregate enters a controller signature, the database becomes the public contract.

When to use

• Adding or reshaping a @RequestBody record, a response record, or a page envelope, and deciding where transport-to-domain mapping happens.
• Fixing an entity, a lazy proxy, or a byte[] leaking into a response.
• Splitting one request DTO into create, update, and action payloads to stop over-posting, or deciding whether a payload is a command or a read model.
• Placing jakarta.validation constraints on a record, or choosing create versus update validation groups.

When not to use

• Status codes, headers, the error body, and endpoint shape: use spring-boot-rest-api.
• Constraint semantics, custom validators, and binding failures: use spring-boot-validation.
• Aggregates, value objects, and invariants to spring-boot-ddd; entity mapping, Specification, and fetch plans to spring-boot-data-jpa.
• The generated OpenAPI document and its schema quality: use spring-boot-openapi.
• Versioned DTO policy and removal dates: use spring-boot-api-versioning.