System Design (LLD)DTO Design

Data Transfer Object (DTO) Design

LevelIntermediate

Duration50 mins

TopicDTO Design

4 / 4

DTO Best Practices

The Art of DTO Design

Creating a DTO is simple—it's just a data container. But creating a well-designed DTO that serves consumers effectively, evolves gracefully, and maintains consistency across a large API surface? That's an art that separates amateur APIs from professional ones.

Poorly designed DTOs lead to:

Consumers constantly confused about field meanings
Breaking changes that require major version bumps
Inconsistent naming that makes the API feel unprofessional
Security vulnerabilities from over-exposure
Performance problems from bloated payloads

This page distills the best practices that experienced API designers have learned—often the hard way—about DTO design.

What You Will Learn

By the end of this page, you will have a comprehensive toolkit of DTO best practices covering naming conventions, nullability, versioning, documentation, security, and common antipatterns to avoid. These practices apply regardless of your technology stack.

Naming Conventions

Names are the primary interface to your DTOs. Consistent, clear naming reduces cognitive load and makes your API feel professional and well-designed.

DTO Type Naming Guidelines

•Use clear suffixes — CreateOrderRequest, OrderResponse, OrderSummaryDTO. The suffix immediately signals purpose.
•Distinguish request from response — Never share DTOs between input and output. OrderDTO for both causes confusion.
•Include operation context — CreateUserRequest, UpdateUserRequest, PatchUserRequest are all different.
•Version when necessary — OrderResponseV1, OrderResponseV2 for breaking changes (though prefer backwards compatibility).
•Avoid abbreviations — CustomerDTO not CustDTO. Clarity trumps brevity in API contracts.

naming-examples.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
// === DTO TYPE NAMING ===
 
// Request DTOs - describe the action
interface CreateOrderRequest { ... }
interface UpdateOrderRequest { ... }
interface CancelOrderRequest { ... }
interface SearchOrdersRequest { ... }
 
// Response DTOs - describe the view
interface OrderResponse { ... }           // Full detail
interface OrderSummaryResponse { ... }    // Abbreviated for lists
interface OrderCreatedResponse { ... }    // Creation confirmation
 
// List responses with pagination
interface OrderListResponse {
    items: OrderSummaryResponse[];
    pagination: PaginationInfo;
}
 
// Composition DTOs
interface OrderWithCustomerResponse {
    order: OrderResponse;
    customer: CustomerSummaryResponse;
}
 
 
// === FIELD NAMING ===
 
interface OrderResponse {
    // ✓ Self-describing, no ambiguity
    orderId: string;          // Not: id (id of what?)
    orderNumber: string;      // Human-readable order reference
    customerEmailAddress: string;  // Not: email (customer's or business's?)
    
    // ✓ Consistent unit suffix for numeric values
    orderTotalCents: number;  // Clear we're using cents
    shippingWeightGrams: number;
    deliveryTimeMinutes: number;
    
    // ✓ Consistent date format indication
    createdAt: string;        // ISO 8601 by convention
    estimatedDeliveryDate: string;  // Not: delivery (is it a date or object?)
    lastUpdatedAt: string;
    
    // ✓ Boolean prefixes
    isActive: boolean;        // Not: active (could be a status)
    isEditable: boolean;
    hasShipped: boolean;
    canBeCancelled: boolean;
    
    // ✓ Enum values as readable strings
    status: 'pending' | 'processing' | 'shipped';  // Not: 1, 2, 3
    paymentMethod: 'credit_card' | 'paypal' | 'bank_transfer';
}

Field Naming Do's and Don'ts
❌ Avoid	✓ Prefer	Reason
`id`	`orderId`	Unambiguous in nested contexts
`email`	`customerEmailAddress`	Clear whose email and what type
`total`	`orderTotalCents`	Units are explicit
`date`	`createdAt`, `shippedAt`	Describes what the date represents
`active`	`isActive`	Boolean intent is clear
`status: 1`	`status: 'pending'`	Self-documenting enum values
`addr`	`shippingAddress`	No abbreviations
`data`	`orderDetails`	Specific, not generic

Consistency Is More Important Than Perfection

Whatever naming convention you choose, apply it consistently across your entire API. An API with consistently applied 'imperfect' conventions is easier to use than one with mixed 'perfect' and 'imperfect' naming. Document your conventions and enforce them in code reviews.

Nullability and Optional Fields

How you handle optional and missing data in DTOs is crucial for consumer experience. Inconsistent null/undefined handling leads to defensive coding and bugs.

nullability-guidelines.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
// === EXPLICIT NULLABILITY ===
 
interface OrderResponse {
    // Required fields - always present
    orderId: string;
    status: string;
    createdAt: string;
    
    // Optional fields - explicitly typed as nullable
    shippedAt: string | null;      // null until shipped
    deliveredAt: string | null;    // null until delivered
    cancelledAt: string | null;    // null unless cancelled
    
    // Optional references - null when not applicable
    tracking: TrackingInfo | null;
    refund: RefundInfo | null;
    
    // Collections - always present, may be empty
    items: OrderItemResponse[];    // Never null, can be []
    discounts: DiscountResponse[]; // Never null, can be []
}
 
 
// === REQUEST DTOs: optional vs required ===
 
interface CreateOrderRequest {
    // Required fields - must be provided
    customerId: string;
    items: CreateOrderItemRequest[];
    shippingAddressId: string;
    
    // Optional fields - use '?' in TypeScript
    // Use explicit markers in other languages
    billingAddressId?: string;       // Defaults to shipping if omitted
    couponCode?: string;             // Optional discount code
    giftMessage?: string;            // Optional gift message
    
    // Optional with known default
    expeditedShipping?: boolean;     // Defaults to false
    signatureRequired?: boolean;     // Defaults to true for expensive orders
}
 
// Never use null for 'not provided' - use field absence instead
// null means "explicitly set to nothing"
interface UpdateOrderRequest {
    // To clear a field, explicitly set null
    giftMessage?: string | null;  // undefined = don't change, null = clear it
}
 
 
// === THE NULL VS UNDEFINED PROBLEM ===
 
// In JSON:
// - undefined fields are omitted entirely
// - null fields are present with null value
 
// This distinction matters for PATCH operations:
{
    "giftMessage": null    // Explicitly clear the gift message
}
// vs
{
    // giftMessage not present - leave existing value unchanged  
}
 
// TypeScript pattern for PATCH DTOs
interface PatchOrderRequest {
    // Each field is optional, but when present can be null
    giftMessage?: string | null;
    shippingAddressId?: string;  // Can't be nulled - must have shipping
}

Nullability Best Practices

•Be explicit — Don't rely on implicit nullability. Type every optional field with | null.
•Collections are never null — Return empty arrays [], not null. Consumers can simply loop without null checks.
•Distinguish undefined from null — In PATCH operations: absent means 'don't change', null means 'clear the value'.
•Document defaults — When optional fields have defaults, document them clearly in the API spec.
•Don't overuse optionality — If a field is almost always present, make it required and handle the rare cases explicitly.

The Billion Dollar Mistake

Tony Hoare called null references his 'billion dollar mistake'. In DTO design, inconsistent or implicit nullability propagates this mistake to every API consumer. Explicit nullability with typed contracts (like TypeScript interfaces or OpenAPI's nullable property) prevents null-related bugs.

Immutability in DTOs

DTOs should be immutable once created. Since they represent a snapshot of data at a point in time, there's no reason to modify them after construction.

immutable-dtos.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
// === ENFORCING IMMUTABILITY ===
 
// TypeScript: Use 'readonly' on all properties
interface OrderResponse {
    readonly orderId: string;
    readonly status: string;
    readonly createdAt: string;
    readonly items: readonly OrderItemResponse[];  // Read-only array too
}
 
// Or use Readonly<T> type
type ImmutableOrderResponse = Readonly<OrderResponse>;
 
// Deep readonly for nested objects
type DeepReadonly<T> = {
    readonly [P in keyof T]: T[P] extends object 
        ? DeepReadonly<T[P]> 
        : T[P];
};
 
type FullyImmutableOrder = DeepReadonly<OrderResponse>;
 
 
// === JAVA/KOTLIN: Records or data classes ===
 
// Java Record (Java 14+)
public record OrderResponse(
    String orderId,
    String status,
    String createdAt,
    List<OrderItemResponse> items
) {
    // Immutable by default - no setters generated
    // Defensive copy for collection
    public OrderResponse {
        items = List.copyOf(items);
    }
}
 
// Kotlin Data Class
data class OrderResponse(
    val orderId: String,
    val status: String,
    val createdAt: String,
    val items: List<OrderItemResponse>  // val = immutable reference
)
 
 
// === C#: Records or init-only properties ===
 
public record OrderResponse(
    string OrderId,
    string Status,
    string CreatedAt,
    IReadOnlyList<OrderItemResponse> Items
);
 
// Or with init-only setters
public class OrderResponse
{
    public string OrderId { get; init; }
    public string Status { get; init; }
    public IReadOnlyList<OrderItemResponse> Items { get; init; }
}
 
 
// === WHY IMMUTABILITY MATTERS FOR DTOs ===
 
// Without immutability - dangerous
function processOrder(order: OrderResponse) {
    order.status = 'modified';  // Oops! Mutated the shared DTO
    return order;
}
 
const order = await api.getOrder('123');
processOrder(order);  // order is now mutated
render(order);  // Rendering incorrect data
 
// With immutability - safe
function processOrder(order: OrderResponse): OrderResponse {
    // order.status = 'modified';  // Compile error!
    
    // Must create new instance with changes
    return { ...order, status: 'modified' };
}

Immutability Enables Safe Caching

When DTOs are immutable, you can safely cache and share them without worrying about one consumer modifying data that another is reading. This is especially valuable in concurrent/async environments and when implementing client-side caching.

Versioning DTOs for API Evolution

APIs evolve over time. New fields are added, old fields become irrelevant, and sometimes breaking changes are unavoidable. Proper DTO versioning strategies enable this evolution without breaking consumers.

Strategy 1: Additive Changes (Preferred)

The best approach is to design DTOs that can grow without breaking existing consumers:

additive-versioning.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
// === ADDITIVE CHANGES (Non-Breaking) ===
 
// Version 1: Original DTO
interface OrderResponseV1 {
    orderId: string;
    status: string;
    totalCents: number;
    createdAt: string;
}
 
// Version 1.1: Added new optional fields (NON-BREAKING)
interface OrderResponse {  // No version suffix needed
    orderId: string;
    status: string;
    totalCents: number;
    createdAt: string;
    
    // New fields are optional, so old clients ignore them
    estimatedDeliveryDate?: string;  // Added in v1.1
    carbonOffsetCents?: number;       // Added in v1.2
    
    // New nested object, optional
    sustainability?: {                 // Added in v1.3
        carbonFootprintKg: number;
        offsetStatus: string;
    };
}
 
// Old clients: { orderId, status, totalCents, createdAt }
// They simply ignore new fields they don't recognize
 
// New clients: Full object with new features
// Compatible with older server responses that lack new fields
 
 
// === RULES FOR ADDITIVE COMPATIBILITY ===
// ✓ Add new optional fields
// ✓ Add new enum values (if client handles unknown values)
// ✓ Add new nested optional objects
// ✓ Add new endpoints
// 
// ✗ Remove fields
// ✗ Rename fields  
// ✗ Change field types
// ✗ Change required to optional
// ✗ Change field semantics

Strategy 2: Explicit Versioned DTOs (For Breaking Changes)

When breaking changes are necessary, maintain parallel DTO versions:

explicit-versioning.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
// === EXPLICIT VERSIONED DTOs ===
 
// api/v1/orders/dto.ts
namespace V1 {
    export interface OrderResponse {
        orderId: string;
        status: string;
        total: number;  // Legacy: dollars as float (bad idea)
        orderDate: string;  // Legacy: different name
    }
}
 
// api/v2/orders/dto.ts  
namespace V2 {
    export interface OrderResponse {
        orderId: string;
        status: OrderStatus;  // Changed to enum
        totalCents: number;   // BREAKING: now cents as integer
        createdAt: string;    // BREAKING: renamed from orderDate
        updatedAt: string;    // New required field
    }
    
    export type OrderStatus = 'pending' | 'processing' | 'shipped' | 'delivered';
}
 
 
// === MAPPER HANDLES BOTH VERSIONS ===
 
class OrderApiMapper {
    toV1Response(order: Order): V1.OrderResponse {
        return {
            orderId: order.id.value,
            status: order.status.toString(),
            total: order.total.amountInCents / 100,  // Convert to dollars for v1
            orderDate: order.createdAt.toISOString(),
        };
    }
    
    toV2Response(order: Order): V2.OrderResponse {
        return {
            orderId: order.id.value,
            status: this.toV2Status(order.status),
            totalCents: order.total.amountInCents,
            createdAt: order.createdAt.toISOString(),
            updatedAt: order.updatedAt.toISOString(),
        };
    }
}
 
 
// === CONTROLLER ROUTES BOTH VERSIONS ===
 
@Controller('api')
class OrderController {
    @Get('v1/orders/:id')
    async getOrderV1(@Param('id') id: string): Promise<V1.OrderResponse> {
        const order = await this.orderService.findById(id);
        return this.mapper.toV1Response(order);
    }
    
    @Get('v2/orders/:id')
    async getOrderV2(@Param('id') id: string): Promise<V2.OrderResponse> {
        const order = await this.orderService.findById(id);
        return this.mapper.toV2Response(order);
    }
}

Version Sunset Policy

Maintain old versions only as long as necessary. Communicate a deprecation timeline (e.g., 'v1 will be removed 12 months after v2 release'), provide migration guides, and monitor v1 usage to know when it's safe to remove.

Strategy 3: Wire Format Versioning

Include version information in the response itself:

wire-format-versioning.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
// Include schema version in response
interface ApiResponse<T> {
    schemaVersion: string;  // '2.1.0'
    data: T;
    deprecations?: DeprecationWarning[];
}
 
interface DeprecationWarning {
    field: string;
    message: string;
    removalDate: string;
    replacement?: string;
}
 
// Example response
const response: ApiResponse<OrderResponse> = {
    schemaVersion: '2.1.0',
    data: {
        orderId: '123',
        // ...
    },
    deprecations: [
        {
            field: 'orderDate',
            message: 'Use createdAt instead',
            removalDate: '2025-01-01',
            replacement: 'createdAt'
        }
    ]
};

DTO Documentation

Well-documented DTOs reduce support burden, prevent misuse, and make your API easier to integrate with. Documentation should live as close to the code as possible.

documented-dto.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
/**
 * Response DTO for order details.
 * 
 * This DTO provides comprehensive order information suitable for
 * order detail pages and receipts.
 * 
 * @see OrderSummaryResponse for list views
 * @see CreateOrderRequest for order creation
 * @since API v2.0
 */
interface OrderResponse {
    /**
     * Unique identifier for the order.
     * Format: UUID v4
     * @example "550e8400-e29b-41d4-a716-446655440000"
     */
    readonly orderId: string;
    
    /**
     * Human-readable order number for customer communication.
     * Format: ORD-YYYY-NNNNNN
     * @example "ORD-2024-001234"
     */
    readonly orderNumber: string;
    
    /**
     * Current order status.
     * 
     * Values:
     * - 'pending': Order placed, awaiting payment confirmation
     * - 'processing': Payment confirmed, preparing for shipment
     * - 'shipped': Order dispatched, in transit
     * - 'delivered': Successfully delivered to customer
     * - 'cancelled': Order cancelled (see cancellationReason)
     * 
     * @see statusChangedAt for when the status last changed
     */
    readonly status: 'pending' | 'processing' | 'shipped' | 'delivered' | 'cancelled';
    
    /**
     * Order total in cents (smallest currency unit).
     * Includes subtotal, tax, shipping, and discounts.
     * 
     * For display, divide by 100 and format with currency symbol.
     * @example 12599 (represents $125.99 USD)
     * @min 0
     */
    readonly totalCents: number;
    
    /**
     * ISO 8601 timestamp when the order was created.
     * Always in UTC timezone.
     * @example "2024-01-15T10:30:00.000Z"
     */
    readonly createdAt: string;
    
    /**
     * ISO 8601 timestamp when order shipped, or null if not yet shipped.
     * Present only when status is 'shipped' or 'delivered'.
     * 
     * @example "2024-01-16T09:15:00.000Z"
     */
    readonly shippedAt: string | null;
    
    /**
     * Whether the order can be modified.
     * 
     * Returns true only when:
     * - Status is 'pending'
     * - Order was created within the last 24 hours
     * - No items have begun fulfillment
     * 
     * Use the PATCH /orders/{id} endpoint to modify.
     */
    readonly isEditable: boolean;
    
    /**
     * List of items in the order.
     * 
     * Always contains at least one item (empty orders cannot exist).
     * Items are sorted by line item ID (creation order).
     * 
     * @minItems 1
     */
    readonly items: OrderItemResponse[];
    
    /**
     * Hypermedia links for related actions and resources.
     * 
     * Links with null values indicate the action is not available
     * for this order's current state.
     */
    readonly links: {
        /** Link to this order (self-reference) */
        readonly self: string;
        
        /** Link to cancel order, or null if not cancellable */
        readonly cancel: string | null;
        
        /** Link to shipment tracking page, or null if not shipped */
        readonly trackShipment: string | null;
    };
}
 
 
// === OpenAPI/Swagger annotations (for auto-generated docs) ===
 
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 
class OrderResponseDto {
    @ApiProperty({
        description: 'Unique order identifier (UUID v4)',
        example: '550e8400-e29b-41d4-a716-446655440000',
        format: 'uuid',
    })
    orderId: string;
    
    @ApiProperty({
        description: 'Order total in cents',
        example: 12599,
        minimum: 0,
    })
    totalCents: number;
    
    @ApiPropertyOptional({
        description: 'Shipment timestamp, null if not shipped',
        example: '2024-01-16T09:15:00.000Z',
        nullable: true,
    })
    shippedAt: string | null;
}

What to Document

•Purpose — What is this DTO used for? Which endpoints return/accept it?
•Field meanings — Don't assume field names are self-explanatory. Describe what each field represents.
•Formats — Date formats (ISO 8601), ID formats (UUID), string patterns (phone, email).
•Units — Currency (cents vs dollars), weight (grams vs kg), time (seconds vs minutes).
•Constraints — Min/max values, required lengths, allowed patterns.
•Null semantics — What does null mean for each nullable field?
•Examples — Concrete example values help more than abstract descriptions.
•Related DTOs — Cross-reference summary vs detail DTOs, request vs response.

Generate Documentation from Code

Use tools like OpenAPI/Swagger, TypeDoc, or JSDoc to generate documentation from annotated code. This keeps documentation synchronized with implementation and reduces the chance of stale docs.

Security Considerations

DTOs are your last line of defense against data exposure. Proper DTO design prevents security vulnerabilities:

DTO Security Practices

•Whitelist, don't blacklist — DTOs should explicitly include fields, not exclude them. New fields are secure by default.
•Role-specific DTOs — Create separate DTOs for different authorization levels (public vs admin).
•No sensitive data in client-bound DTOs — Passwords, tokens, internal IDs, PII unless necessary.
•Validate input DTOs — Never trust client data. Validate type, format, range, and length.
•Sanitize output — Escape or remove potentially dangerous content (HTML, scripts).
•Audit what you expose — Regularly review DTOs to ensure no accidental exposure.

role-specific-dtos.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
// === ROLE-SPECIFIC DTOs ===
 
// Public DTO - minimal, safe data
interface UserPublicProfileDTO {
    readonly userId: string;
    readonly displayName: string;
    readonly avatarUrl: string;
    readonly memberSince: string;
    // NO: email, phone, address, etc.
}
 
// Self-profile DTO - user can see their own data
interface UserSelfProfileDTO {
    readonly userId: string;
    readonly displayName: string;
    readonly email: string;
    readonly phone: string | null;
    readonly emailVerified: boolean;
    readonly settings: UserSettingsDTO;
    // NO: internal flags, admin notes, etc.
}
 
// Admin DTO - operational data for support
interface UserAdminViewDTO {
    readonly userId: string;
    readonly displayName: string;
    readonly email: string;
    readonly phone: string | null;
    readonly accountStatus: 'active' | 'suspended' | 'banned';
    readonly suspensionReason: string | null;
    readonly lastLoginAt: string | null;
    readonly failedLoginAttempts: number;
    readonly createdByReferral: string | null;
    readonly orderCount: number;
    readonly totalSpentCents: number;
    // Still NO: password hashes, SSN, etc.
}
 
// Controller returns appropriate DTO based on requester
@Get('/users/:id')
async getUser(
    @Param('id') userId: string,
    @CurrentUser() requester: User
): Promise<UserPublicProfileDTO | UserSelfProfileDTO | UserAdminViewDTO> {
    
    const user = await this.userService.findById(userId);
    
    // Own profile - see personal data
    if (requester.id === userId) {
        return this.mapper.toSelfProfileDTO(user);
    }
    
    // Admin - see operational data
    if (requester.hasRole('admin')) {
        return this.mapper.toAdminViewDTO(user);
    }
    
    // Everyone else - public data only
    return this.mapper.toPublicProfileDTO(user);
}
 
 
// === INPUT VALIDATION ===
 
class CreateUserRequestDTO {
    @IsString()
    @Length(2, 50)
    @Matches(/^[a-zA-Z0-9_-]+$/, {
        message: 'Username can only contain letters, numbers, underscores, and hyphens'
    })
    username: string;
    
    @IsEmail()
    @MaxLength(255)
    @Transform(({ value }) => value.toLowerCase().trim())  // Normalize
    email: string;
    
    @IsString()
    @MinLength(12, { message: 'Password must be at least 12 characters' })
    @MaxLength(128)
    @Matches(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/, {
        message: 'Password must contain uppercase, lowercase, and number'
    })
    password: string;  // Will be hashed - never stored as-is
    
    @IsOptional()
    @IsString()
    @MaxLength(200)
    @Transform(({ value }) => sanitizeHtml(value))  // Remove dangerous content
    bio?: string;
}

Real Breach: Accidental Exposure

In 2019, Facebook inadvertently exposed millions of user phone numbers through an API that returned full User objects instead of a minimal DTO. The internal phone number field was never meant to be public but wasn't explicitly excluded. Whitelist-based DTOs would have prevented this.

Common DTO Antipatterns

Learning what not to do is as important as learning best practices. These antipatterns appear frequently in real codebases:

Antipattern 1: The God DTO

One DTO that tries to serve all purposes:

god-dto-antipattern.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// ❌ THE GOD DTO - Does everything, confuses everyone
interface OrderDTO {
    // Used for creation
    customerId?: string;
    items?: CreateItemDTO[];
    
    // Used for responses
    orderId?: string;
    orderNumber?: string;
    status?: string;
    createdAt?: string;
    
    // Used for updates
    newStatus?: string;
    updateReason?: string;
    
    // Used for admin views
    fraudScore?: number;
    internalNotes?: string;
    
    // Everything optional because different uses need different fields
    // Result: No one knows what to actually provide or expect
}
 
// ✓ SOLUTION: Purpose-specific DTOs
interface CreateOrderRequest { ... }
interface UpdateOrderStatusRequest { ... }
interface OrderResponse { ... }
interface OrderAdminView { ... }

Antipattern 2: Primitive Obsession in Response DTOs

While DTOs use primitives for serialization, don't lose structure:

structure-antipattern.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// ❌ TOO FLAT - Lost meaningful structure
interface OrderDTO {
    orderId: string;
    customerName: string;
    customerEmail: string;
    customerPhone: string;
    shippingStreet: string;
    shippingCity: string;
    shippingState: string;
    shippingZip: string;
    shippingCountry: string;
    billingStreet: string;
    billingCity: string;
    // ... 30 more flat fields
}
 
// ✓ STRUCTURED BUT SERIALIZABLE
interface OrderDTO {
    orderId: string;
    customer: CustomerSummaryDTO;
    shippingAddress: AddressDTO;
    billingAddress: AddressDTO;
    // Logical grouping preserves meaning
}

Antipattern 3: Leaky Abstraction

Exposing implementation details through DTOs:

leaky-antipattern.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// ❌ LEAKY ABSTRACTION
interface OrderDTO {
    _id: ObjectId;                    // MongoDB implementation detail
    __v: number;                      // Mongoose version key
    _createdBy: string;               // Internal audit field
    hibernateProxy: boolean;          // ORM mechanism exposed
    items: HibernatePersistentSet;    // ORM collection type
    orderStatusId: number;            // Exposes database FK
}
 
// ✓ CLEAN ABSTRACTION
interface OrderDTO {
    orderId: string;                  // Clean string ID
    createdAt: string;                // Standard timestamp
    items: OrderItemDTO[];            // Plain array
    status: 'pending' | 'shipped';    // Meaningful enum
}

Antipattern 4: Inconsistent Conventions

inconsistent-antipattern.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
// ❌ INCONSISTENT - Same API, different conventions
interface OrderDTO {
    order_id: string;          // snake_case
    orderNumber: string;       // camelCase
    CreatedAt: string;         // PascalCase
    TOTAL: number;             // SCREAMING_CASE
    
    is_active: boolean;        // snake_case boolean
    hasShipped: boolean;       // camelCase boolean
    
    total_amount: number;      // Dollars?
    shipping_cents: number;    // Cents?
    
    date: string;              // Which date?
    timestamp: number;         // Unix timestamp?
}
 
// ✓ CONSISTENT - Pick conventions and stick to them
interface OrderDTO {
    orderId: string;           // camelCase everywhere
    orderNumber: string;
    createdAt: string;         // ISO 8601 string
    totalCents: number;        // Always cents, suffixed
    shippingCents: number;
    isActive: boolean;         // is/has prefix for booleans
    hasShipped: boolean;
}

Antipatterns Compound

These antipatterns often appear together. A project with a God DTO usually also has inconsistent naming and leaky abstractions. Fixing one antipattern often makes others visible. Invest in DTO design guidelines and enforce them from the start.

Summary: DTO Best Practices

DTO design is where API craftsmanship shows. These practices, applied consistently, result in APIs that are a pleasure to consume:

Key Takeaways

•Naming is your interface — Consistent, self-describing names with clear suffixes reduce confusion and make APIs feel professional.
•Explicit nullability prevents bugs — Type every optional field. Return empty arrays, not null. Distinguish undefined from null for PATCH semantics.
•Immutable DTOs are safer — Use readonly/final modifiers. Immutability enables caching and prevents subtle mutation bugs.
•Design for evolution — Prefer additive changes. When breaking changes are necessary, version explicitly and maintain both versions during transition.
•Document thoroughly — Field meanings, formats, units, constraints, and examples. Generate docs from code to prevent staleness.
•Security is paramount — Whitelist fields in DTOs. Create role-specific views. Validate all inputs. Audit what you expose.
•Avoid common antipatterns — No God DTOs, no leaky abstractions, no inconsistent conventions. Purpose-specific, clean DTOs.

DTO Best Practices Quick Reference
Category	Practice
Naming	Clear suffixes (Request/Response), no abbreviations
Nullability	Explicit types, empty arrays not null
Immutability	Readonly properties, defensive copies
Versioning	Additive changes; explicit versioning when needed
Documentation	Field descriptions, examples, constraints
Security	Whitelist fields, role-specific DTOs, input validation
Structure	Purpose-specific, not God DTOs

Module Complete:

You've now completed the DTO Design module. You understand what DTOs are, how they differ from domain objects, strategies for mapping between them, and the best practices that lead to well-designed APIs.

The principles learned here apply beyond DTOs—to any API contract design, message payloads, or data exchange format. The core insight remains: deliberately designed boundaries that decouple internal implementation from external contracts enable systems to evolve gracefully.

Module Complete

Congratulations! You've mastered DTO Design. You can now create Data Transfer Objects that are clear, secure, evolvable, and a pleasure for API consumers to work with. Apply these practices to build APIs that stand the test of time.

4 / 4

Loading learning content...

System Design (LLD)DTO Design

Data Transfer Object (DTO) Design

LevelIntermediate

Duration50 mins

TopicDTO Design

4 / 4

DTO Best Practices

The Art of DTO Design

Poorly designed DTOs lead to:

Consumers constantly confused about field meanings
Breaking changes that require major version bumps
Inconsistent naming that makes the API feel unprofessional
Security vulnerabilities from over-exposure
Performance problems from bloated payloads

This page distills the best practices that experienced API designers have learned—often the hard way—about DTO design.

What You Will Learn

Naming Conventions

Names are the primary interface to your DTOs. Consistent, clear naming reduces cognitive load and makes your API feel professional and well-designed.

DTO Type Naming Guidelines

•Use clear suffixes — CreateOrderRequest, OrderResponse, OrderSummaryDTO. The suffix immediately signals purpose.
•Distinguish request from response — Never share DTOs between input and output. OrderDTO for both causes confusion.
•Include operation context — CreateUserRequest, UpdateUserRequest, PatchUserRequest are all different.
•Version when necessary — OrderResponseV1, OrderResponseV2 for breaking changes (though prefer backwards compatibility).
•Avoid abbreviations — CustomerDTO not CustDTO. Clarity trumps brevity in API contracts.

naming-examples.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
// === DTO TYPE NAMING ===
 
// Request DTOs - describe the action
interface CreateOrderRequest { ... }
interface UpdateOrderRequest { ... }
interface CancelOrderRequest { ... }
interface SearchOrdersRequest { ... }
 
// Response DTOs - describe the view
interface OrderResponse { ... }           // Full detail
interface OrderSummaryResponse { ... }    // Abbreviated for lists
interface OrderCreatedResponse { ... }    // Creation confirmation
 
// List responses with pagination
interface OrderListResponse {
    items: OrderSummaryResponse[];
    pagination: PaginationInfo;
}
 
// Composition DTOs
interface OrderWithCustomerResponse {
    order: OrderResponse;
    customer: CustomerSummaryResponse;
}
 
 
// === FIELD NAMING ===
 
interface OrderResponse {
    // ✓ Self-describing, no ambiguity
    orderId: string;          // Not: id (id of what?)
    orderNumber: string;      // Human-readable order reference
    customerEmailAddress: string;  // Not: email (customer's or business's?)
    
    // ✓ Consistent unit suffix for numeric values
    orderTotalCents: number;  // Clear we're using cents
    shippingWeightGrams: number;
    deliveryTimeMinutes: number;
    
    // ✓ Consistent date format indication
    createdAt: string;        // ISO 8601 by convention
    estimatedDeliveryDate: string;  // Not: delivery (is it a date or object?)
    lastUpdatedAt: string;
    
    // ✓ Boolean prefixes
    isActive: boolean;        // Not: active (could be a status)
    isEditable: boolean;
    hasShipped: boolean;
    canBeCancelled: boolean;
    
    // ✓ Enum values as readable strings
    status: 'pending' | 'processing' | 'shipped';  // Not: 1, 2, 3
    paymentMethod: 'credit_card' | 'paypal' | 'bank_transfer';
}

Field Naming Do's and Don'ts
❌ Avoid	✓ Prefer	Reason
`id`	`orderId`	Unambiguous in nested contexts
`email`	`customerEmailAddress`	Clear whose email and what type
`total`	`orderTotalCents`	Units are explicit
`date`	`createdAt`, `shippedAt`	Describes what the date represents
`active`	`isActive`	Boolean intent is clear
`status: 1`	`status: 'pending'`	Self-documenting enum values
`addr`	`shippingAddress`	No abbreviations
`data`	`orderDetails`	Specific, not generic

Consistency Is More Important Than Perfection

Nullability and Optional Fields

How you handle optional and missing data in DTOs is crucial for consumer experience. Inconsistent null/undefined handling leads to defensive coding and bugs.

nullability-guidelines.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
// === EXPLICIT NULLABILITY ===
 
interface OrderResponse {
    // Required fields - always present
    orderId: string;
    status: string;
    createdAt: string;
    
    // Optional fields - explicitly typed as nullable
    shippedAt: string | null;      // null until shipped
    deliveredAt: string | null;    // null until delivered
    cancelledAt: string | null;    // null unless cancelled
    
    // Optional references - null when not applicable
    tracking: TrackingInfo | null;
    refund: RefundInfo | null;
    
    // Collections - always present, may be empty
    items: OrderItemResponse[];    // Never null, can be []
    discounts: DiscountResponse[]; // Never null, can be []
}
 
 
// === REQUEST DTOs: optional vs required ===
 
interface CreateOrderRequest {
    // Required fields - must be provided
    customerId: string;
    items: CreateOrderItemRequest[];
    shippingAddressId: string;
    
    // Optional fields - use '?' in TypeScript
    // Use explicit markers in other languages
    billingAddressId?: string;       // Defaults to shipping if omitted
    couponCode?: string;             // Optional discount code
    giftMessage?: string;            // Optional gift message
    
    // Optional with known default
    expeditedShipping?: boolean;     // Defaults to false
    signatureRequired?: boolean;     // Defaults to true for expensive orders
}
 
// Never use null for 'not provided' - use field absence instead
// null means "explicitly set to nothing"
interface UpdateOrderRequest {
    // To clear a field, explicitly set null
    giftMessage?: string | null;  // undefined = don't change, null = clear it
}
 
 
// === THE NULL VS UNDEFINED PROBLEM ===
 
// In JSON:
// - undefined fields are omitted entirely
// - null fields are present with null value
 
// This distinction matters for PATCH operations:
{
    "giftMessage": null    // Explicitly clear the gift message
}
// vs
{
    // giftMessage not present - leave existing value unchanged  
}
 
// TypeScript pattern for PATCH DTOs
interface PatchOrderRequest {
    // Each field is optional, but when present can be null
    giftMessage?: string | null;
    shippingAddressId?: string;  // Can't be nulled - must have shipping
}

Nullability Best Practices

•Be explicit — Don't rely on implicit nullability. Type every optional field with | null.
•Collections are never null — Return empty arrays [], not null. Consumers can simply loop without null checks.
•Distinguish undefined from null — In PATCH operations: absent means 'don't change', null means 'clear the value'.
•Document defaults — When optional fields have defaults, document them clearly in the API spec.
•Don't overuse optionality — If a field is almost always present, make it required and handle the rare cases explicitly.

The Billion Dollar Mistake

Immutability in DTOs

DTOs should be immutable once created. Since they represent a snapshot of data at a point in time, there's no reason to modify them after construction.

immutable-dtos.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
// === ENFORCING IMMUTABILITY ===
 
// TypeScript: Use 'readonly' on all properties
interface OrderResponse {
    readonly orderId: string;
    readonly status: string;
    readonly createdAt: string;
    readonly items: readonly OrderItemResponse[];  // Read-only array too
}
 
// Or use Readonly<T> type
type ImmutableOrderResponse = Readonly<OrderResponse>;
 
// Deep readonly for nested objects
type DeepReadonly<T> = {
    readonly [P in keyof T]: T[P] extends object 
        ? DeepReadonly<T[P]> 
        : T[P];
};
 
type FullyImmutableOrder = DeepReadonly<OrderResponse>;
 
 
// === JAVA/KOTLIN: Records or data classes ===
 
// Java Record (Java 14+)
public record OrderResponse(
    String orderId,
    String status,
    String createdAt,
    List<OrderItemResponse> items
) {
    // Immutable by default - no setters generated
    // Defensive copy for collection
    public OrderResponse {
        items = List.copyOf(items);
    }
}
 
// Kotlin Data Class
data class OrderResponse(
    val orderId: String,
    val status: String,
    val createdAt: String,
    val items: List<OrderItemResponse>  // val = immutable reference
)
 
 
// === C#: Records or init-only properties ===
 
public record OrderResponse(
    string OrderId,
    string Status,
    string CreatedAt,
    IReadOnlyList<OrderItemResponse> Items
);
 
// Or with init-only setters
public class OrderResponse
{
    public string OrderId { get; init; }
    public string Status { get; init; }
    public IReadOnlyList<OrderItemResponse> Items { get; init; }
}
 
 
// === WHY IMMUTABILITY MATTERS FOR DTOs ===
 
// Without immutability - dangerous
function processOrder(order: OrderResponse) {
    order.status = 'modified';  // Oops! Mutated the shared DTO
    return order;
}
 
const order = await api.getOrder('123');
processOrder(order);  // order is now mutated
render(order);  // Rendering incorrect data
 
// With immutability - safe
function processOrder(order: OrderResponse): OrderResponse {
    // order.status = 'modified';  // Compile error!
    
    // Must create new instance with changes
    return { ...order, status: 'modified' };
}

Immutability Enables Safe Caching

Versioning DTOs for API Evolution

Strategy 1: Additive Changes (Preferred)

The best approach is to design DTOs that can grow without breaking existing consumers:

additive-versioning.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
// === ADDITIVE CHANGES (Non-Breaking) ===
 
// Version 1: Original DTO
interface OrderResponseV1 {
    orderId: string;
    status: string;
    totalCents: number;
    createdAt: string;
}
 
// Version 1.1: Added new optional fields (NON-BREAKING)
interface OrderResponse {  // No version suffix needed
    orderId: string;
    status: string;
    totalCents: number;
    createdAt: string;
    
    // New fields are optional, so old clients ignore them
    estimatedDeliveryDate?: string;  // Added in v1.1
    carbonOffsetCents?: number;       // Added in v1.2
    
    // New nested object, optional
    sustainability?: {                 // Added in v1.3
        carbonFootprintKg: number;
        offsetStatus: string;
    };
}
 
// Old clients: { orderId, status, totalCents, createdAt }
// They simply ignore new fields they don't recognize
 
// New clients: Full object with new features
// Compatible with older server responses that lack new fields
 
 
// === RULES FOR ADDITIVE COMPATIBILITY ===
// ✓ Add new optional fields
// ✓ Add new enum values (if client handles unknown values)
// ✓ Add new nested optional objects
// ✓ Add new endpoints
// 
// ✗ Remove fields
// ✗ Rename fields  
// ✗ Change field types
// ✗ Change required to optional
// ✗ Change field semantics

Strategy 2: Explicit Versioned DTOs (For Breaking Changes)

When breaking changes are necessary, maintain parallel DTO versions:

explicit-versioning.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
// === EXPLICIT VERSIONED DTOs ===
 
// api/v1/orders/dto.ts
namespace V1 {
    export interface OrderResponse {
        orderId: string;
        status: string;
        total: number;  // Legacy: dollars as float (bad idea)
        orderDate: string;  // Legacy: different name
    }
}
 
// api/v2/orders/dto.ts  
namespace V2 {
    export interface OrderResponse {
        orderId: string;
        status: OrderStatus;  // Changed to enum
        totalCents: number;   // BREAKING: now cents as integer
        createdAt: string;    // BREAKING: renamed from orderDate
        updatedAt: string;    // New required field
    }
    
    export type OrderStatus = 'pending' | 'processing' | 'shipped' | 'delivered';
}
 
 
// === MAPPER HANDLES BOTH VERSIONS ===
 
class OrderApiMapper {
    toV1Response(order: Order): V1.OrderResponse {
        return {
            orderId: order.id.value,
            status: order.status.toString(),
            total: order.total.amountInCents / 100,  // Convert to dollars for v1
            orderDate: order.createdAt.toISOString(),
        };
    }
    
    toV2Response(order: Order): V2.OrderResponse {
        return {
            orderId: order.id.value,
            status: this.toV2Status(order.status),
            totalCents: order.total.amountInCents,
            createdAt: order.createdAt.toISOString(),
            updatedAt: order.updatedAt.toISOString(),
        };
    }
}
 
 
// === CONTROLLER ROUTES BOTH VERSIONS ===
 
@Controller('api')
class OrderController {
    @Get('v1/orders/:id')
    async getOrderV1(@Param('id') id: string): Promise<V1.OrderResponse> {
        const order = await this.orderService.findById(id);
        return this.mapper.toV1Response(order);
    }
    
    @Get('v2/orders/:id')
    async getOrderV2(@Param('id') id: string): Promise<V2.OrderResponse> {
        const order = await this.orderService.findById(id);
        return this.mapper.toV2Response(order);
    }
}

Version Sunset Policy

Strategy 3: Wire Format Versioning

Include version information in the response itself:

wire-format-versioning.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
// Include schema version in response
interface ApiResponse<T> {
    schemaVersion: string;  // '2.1.0'
    data: T;
    deprecations?: DeprecationWarning[];
}
 
interface DeprecationWarning {
    field: string;
    message: string;
    removalDate: string;
    replacement?: string;
}
 
// Example response
const response: ApiResponse<OrderResponse> = {
    schemaVersion: '2.1.0',
    data: {
        orderId: '123',
        // ...
    },
    deprecations: [
        {
            field: 'orderDate',
            message: 'Use createdAt instead',
            removalDate: '2025-01-01',
            replacement: 'createdAt'
        }
    ]
};

DTO Documentation

Well-documented DTOs reduce support burden, prevent misuse, and make your API easier to integrate with. Documentation should live as close to the code as possible.

documented-dto.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
/**
 * Response DTO for order details.
 * 
 * This DTO provides comprehensive order information suitable for
 * order detail pages and receipts.
 * 
 * @see OrderSummaryResponse for list views
 * @see CreateOrderRequest for order creation
 * @since API v2.0
 */
interface OrderResponse {
    /**
     * Unique identifier for the order.
     * Format: UUID v4
     * @example "550e8400-e29b-41d4-a716-446655440000"
     */
    readonly orderId: string;
    
    /**
     * Human-readable order number for customer communication.
     * Format: ORD-YYYY-NNNNNN
     * @example "ORD-2024-001234"
     */
    readonly orderNumber: string;
    
    /**
     * Current order status.
     * 
     * Values:
     * - 'pending': Order placed, awaiting payment confirmation
     * - 'processing': Payment confirmed, preparing for shipment
     * - 'shipped': Order dispatched, in transit
     * - 'delivered': Successfully delivered to customer
     * - 'cancelled': Order cancelled (see cancellationReason)
     * 
     * @see statusChangedAt for when the status last changed
     */
    readonly status: 'pending' | 'processing' | 'shipped' | 'delivered' | 'cancelled';
    
    /**
     * Order total in cents (smallest currency unit).
     * Includes subtotal, tax, shipping, and discounts.
     * 
     * For display, divide by 100 and format with currency symbol.
     * @example 12599 (represents $125.99 USD)
     * @min 0
     */
    readonly totalCents: number;
    
    /**
     * ISO 8601 timestamp when the order was created.
     * Always in UTC timezone.
     * @example "2024-01-15T10:30:00.000Z"
     */
    readonly createdAt: string;
    
    /**
     * ISO 8601 timestamp when order shipped, or null if not yet shipped.
     * Present only when status is 'shipped' or 'delivered'.
     * 
     * @example "2024-01-16T09:15:00.000Z"
     */
    readonly shippedAt: string | null;
    
    /**
     * Whether the order can be modified.
     * 
     * Returns true only when:
     * - Status is 'pending'
     * - Order was created within the last 24 hours
     * - No items have begun fulfillment
     * 
     * Use the PATCH /orders/{id} endpoint to modify.
     */
    readonly isEditable: boolean;
    
    /**
     * List of items in the order.
     * 
     * Always contains at least one item (empty orders cannot exist).
     * Items are sorted by line item ID (creation order).
     * 
     * @minItems 1
     */
    readonly items: OrderItemResponse[];
    
    /**
     * Hypermedia links for related actions and resources.
     * 
     * Links with null values indicate the action is not available
     * for this order's current state.
     */
    readonly links: {
        /** Link to this order (self-reference) */
        readonly self: string;
        
        /** Link to cancel order, or null if not cancellable */
        readonly cancel: string | null;
        
        /** Link to shipment tracking page, or null if not shipped */
        readonly trackShipment: string | null;
    };
}
 
 
// === OpenAPI/Swagger annotations (for auto-generated docs) ===
 
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 
class OrderResponseDto {
    @ApiProperty({
        description: 'Unique order identifier (UUID v4)',
        example: '550e8400-e29b-41d4-a716-446655440000',
        format: 'uuid',
    })
    orderId: string;
    
    @ApiProperty({
        description: 'Order total in cents',
        example: 12599,
        minimum: 0,
    })
    totalCents: number;
    
    @ApiPropertyOptional({
        description: 'Shipment timestamp, null if not shipped',
        example: '2024-01-16T09:15:00.000Z',
        nullable: true,
    })
    shippedAt: string | null;
}

What to Document

•Purpose — What is this DTO used for? Which endpoints return/accept it?
•Field meanings — Don't assume field names are self-explanatory. Describe what each field represents.
•Formats — Date formats (ISO 8601), ID formats (UUID), string patterns (phone, email).
•Units — Currency (cents vs dollars), weight (grams vs kg), time (seconds vs minutes).
•Constraints — Min/max values, required lengths, allowed patterns.
•Null semantics — What does null mean for each nullable field?
•Examples — Concrete example values help more than abstract descriptions.
•Related DTOs — Cross-reference summary vs detail DTOs, request vs response.

Generate Documentation from Code

Use tools like OpenAPI/Swagger, TypeDoc, or JSDoc to generate documentation from annotated code. This keeps documentation synchronized with implementation and reduces the chance of stale docs.

Security Considerations

DTOs are your last line of defense against data exposure. Proper DTO design prevents security vulnerabilities:

DTO Security Practices

•Whitelist, don't blacklist — DTOs should explicitly include fields, not exclude them. New fields are secure by default.
•Role-specific DTOs — Create separate DTOs for different authorization levels (public vs admin).
•No sensitive data in client-bound DTOs — Passwords, tokens, internal IDs, PII unless necessary.
•Validate input DTOs — Never trust client data. Validate type, format, range, and length.
•Sanitize output — Escape or remove potentially dangerous content (HTML, scripts).
•Audit what you expose — Regularly review DTOs to ensure no accidental exposure.

role-specific-dtos.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
// === ROLE-SPECIFIC DTOs ===
 
// Public DTO - minimal, safe data
interface UserPublicProfileDTO {
    readonly userId: string;
    readonly displayName: string;
    readonly avatarUrl: string;
    readonly memberSince: string;
    // NO: email, phone, address, etc.
}
 
// Self-profile DTO - user can see their own data
interface UserSelfProfileDTO {
    readonly userId: string;
    readonly displayName: string;
    readonly email: string;
    readonly phone: string | null;
    readonly emailVerified: boolean;
    readonly settings: UserSettingsDTO;
    // NO: internal flags, admin notes, etc.
}
 
// Admin DTO - operational data for support
interface UserAdminViewDTO {
    readonly userId: string;
    readonly displayName: string;
    readonly email: string;
    readonly phone: string | null;
    readonly accountStatus: 'active' | 'suspended' | 'banned';
    readonly suspensionReason: string | null;
    readonly lastLoginAt: string | null;
    readonly failedLoginAttempts: number;
    readonly createdByReferral: string | null;
    readonly orderCount: number;
    readonly totalSpentCents: number;
    // Still NO: password hashes, SSN, etc.
}
 
// Controller returns appropriate DTO based on requester
@Get('/users/:id')
async getUser(
    @Param('id') userId: string,
    @CurrentUser() requester: User
): Promise<UserPublicProfileDTO | UserSelfProfileDTO | UserAdminViewDTO> {
    
    const user = await this.userService.findById(userId);
    
    // Own profile - see personal data
    if (requester.id === userId) {
        return this.mapper.toSelfProfileDTO(user);
    }
    
    // Admin - see operational data
    if (requester.hasRole('admin')) {
        return this.mapper.toAdminViewDTO(user);
    }
    
    // Everyone else - public data only
    return this.mapper.toPublicProfileDTO(user);
}
 
 
// === INPUT VALIDATION ===
 
class CreateUserRequestDTO {
    @IsString()
    @Length(2, 50)
    @Matches(/^[a-zA-Z0-9_-]+$/, {
        message: 'Username can only contain letters, numbers, underscores, and hyphens'
    })
    username: string;
    
    @IsEmail()
    @MaxLength(255)
    @Transform(({ value }) => value.toLowerCase().trim())  // Normalize
    email: string;
    
    @IsString()
    @MinLength(12, { message: 'Password must be at least 12 characters' })
    @MaxLength(128)
    @Matches(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/, {
        message: 'Password must contain uppercase, lowercase, and number'
    })
    password: string;  // Will be hashed - never stored as-is
    
    @IsOptional()
    @IsString()
    @MaxLength(200)
    @Transform(({ value }) => sanitizeHtml(value))  // Remove dangerous content
    bio?: string;
}

Real Breach: Accidental Exposure

Common DTO Antipatterns

Learning what not to do is as important as learning best practices. These antipatterns appear frequently in real codebases:

Antipattern 1: The God DTO

One DTO that tries to serve all purposes:

god-dto-antipattern.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// ❌ THE GOD DTO - Does everything, confuses everyone
interface OrderDTO {
    // Used for creation
    customerId?: string;
    items?: CreateItemDTO[];
    
    // Used for responses
    orderId?: string;
    orderNumber?: string;
    status?: string;
    createdAt?: string;
    
    // Used for updates
    newStatus?: string;
    updateReason?: string;
    
    // Used for admin views
    fraudScore?: number;
    internalNotes?: string;
    
    // Everything optional because different uses need different fields
    // Result: No one knows what to actually provide or expect
}
 
// ✓ SOLUTION: Purpose-specific DTOs
interface CreateOrderRequest { ... }
interface UpdateOrderStatusRequest { ... }
interface OrderResponse { ... }
interface OrderAdminView { ... }

Antipattern 2: Primitive Obsession in Response DTOs

While DTOs use primitives for serialization, don't lose structure:

structure-antipattern.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// ❌ TOO FLAT - Lost meaningful structure
interface OrderDTO {
    orderId: string;
    customerName: string;
    customerEmail: string;
    customerPhone: string;
    shippingStreet: string;
    shippingCity: string;
    shippingState: string;
    shippingZip: string;
    shippingCountry: string;
    billingStreet: string;
    billingCity: string;
    // ... 30 more flat fields
}
 
// ✓ STRUCTURED BUT SERIALIZABLE
interface OrderDTO {
    orderId: string;
    customer: CustomerSummaryDTO;
    shippingAddress: AddressDTO;
    billingAddress: AddressDTO;
    // Logical grouping preserves meaning
}

Antipattern 3: Leaky Abstraction

Exposing implementation details through DTOs:

leaky-antipattern.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// ❌ LEAKY ABSTRACTION
interface OrderDTO {
    _id: ObjectId;                    // MongoDB implementation detail
    __v: number;                      // Mongoose version key
    _createdBy: string;               // Internal audit field
    hibernateProxy: boolean;          // ORM mechanism exposed
    items: HibernatePersistentSet;    // ORM collection type
    orderStatusId: number;            // Exposes database FK
}
 
// ✓ CLEAN ABSTRACTION
interface OrderDTO {
    orderId: string;                  // Clean string ID
    createdAt: string;                // Standard timestamp
    items: OrderItemDTO[];            // Plain array
    status: 'pending' | 'shipped';    // Meaningful enum
}

Antipattern 4: Inconsistent Conventions

inconsistent-antipattern.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
// ❌ INCONSISTENT - Same API, different conventions
interface OrderDTO {
    order_id: string;          // snake_case
    orderNumber: string;       // camelCase
    CreatedAt: string;         // PascalCase
    TOTAL: number;             // SCREAMING_CASE
    
    is_active: boolean;        // snake_case boolean
    hasShipped: boolean;       // camelCase boolean
    
    total_amount: number;      // Dollars?
    shipping_cents: number;    // Cents?
    
    date: string;              // Which date?
    timestamp: number;         // Unix timestamp?
}
 
// ✓ CONSISTENT - Pick conventions and stick to them
interface OrderDTO {
    orderId: string;           // camelCase everywhere
    orderNumber: string;
    createdAt: string;         // ISO 8601 string
    totalCents: number;        // Always cents, suffixed
    shippingCents: number;
    isActive: boolean;         // is/has prefix for booleans
    hasShipped: boolean;
}

Antipatterns Compound

Summary: DTO Best Practices

DTO design is where API craftsmanship shows. These practices, applied consistently, result in APIs that are a pleasure to consume:

Key Takeaways

•Naming is your interface — Consistent, self-describing names with clear suffixes reduce confusion and make APIs feel professional.
•Explicit nullability prevents bugs — Type every optional field. Return empty arrays, not null. Distinguish undefined from null for PATCH semantics.
•Immutable DTOs are safer — Use readonly/final modifiers. Immutability enables caching and prevents subtle mutation bugs.
•Design for evolution — Prefer additive changes. When breaking changes are necessary, version explicitly and maintain both versions during transition.
•Document thoroughly — Field meanings, formats, units, constraints, and examples. Generate docs from code to prevent staleness.
•Security is paramount — Whitelist fields in DTOs. Create role-specific views. Validate all inputs. Audit what you expose.
•Avoid common antipatterns — No God DTOs, no leaky abstractions, no inconsistent conventions. Purpose-specific, clean DTOs.

DTO Best Practices Quick Reference
Category	Practice
Naming	Clear suffixes (Request/Response), no abbreviations
Nullability	Explicit types, empty arrays not null
Immutability	Readonly properties, defensive copies
Versioning	Additive changes; explicit versioning when needed
Documentation	Field descriptions, examples, constraints
Security	Whitelist fields, role-specific DTOs, input validation
Structure	Purpose-specific, not God DTOs

Module Complete:

Module Complete

4 / 4