System Design (LLD)Domain Events

Domain Events

LevelIntermediate

Duration60 mins

TopicDomain Events

2 / 4

Event Naming and Structure

The Language of Your Events

If domain events are the historical record of your system, then naming and structure are the vocabulary and grammar of that record. Poorly named events become cryptic references that future developers struggle to interpret. Well-named events read like a chronicle of business operations—clear, precise, and immediately understandable.

More than aesthetics, consistent event design enables:

Schema evolution without breaking consumers
Cross-team understanding without extensive documentation
Tooling and automation that works across all events
Long-term maintainability as systems grow

This page establishes the naming conventions and structural patterns that make your domain events a reliable foundation for your architecture.

What You Will Learn

By the end of this page, you will master the naming conventions that make events self-documenting, understand the essential metadata every event needs, learn strategies for versioning and schema evolution, and recognize common anti-patterns in event design.

Naming Conventions

Event naming is deceptively important. A well-named event immediately communicates its meaning, while a poorly named event obscures intent and leads to misunderstandings. Follow these principles for consistent, clear event names.

Event Naming Principles

•Use Past Tense — Events describe something that happened: OrderPlaced, not PlaceOrder. Past tense emphasizes that events are historical facts, not commands or requests.
•Use Ubiquitous Language — Names should come from the domain vocabulary that business experts use. ShipmentDispatched is better than OrderFulfillmentProcessExecuted.
•Be Specific, Not Generic — Avoid generic names like OrderUpdated or EntityChanged. These lack semantic meaning. What specifically happened? OrderShipped, OrderCancelled, PriceAdjusted.
•Include the Subject — The event name should include what was affected: Order + Placed = OrderPlaced. This makes the event self-documenting.
•Avoid Technical Terms — Events are part of the domain model, not infrastructure. Avoid names like OrderRecordInserted or OrderRowCreated.
•Consider the Reader — Names should be understandable to someone unfamiliar with your specific implementation. Would a new team member or domain expert understand what this event means?

Event Naming: Good vs Poor Examples
Poor Name	Why It's Poor	Better Name
OrderUpdated	What update? Status? Items? Address?	OrderShipped, OrderItemRemoved, ShippingAddressChanged
OrderEvent	Tells nothing about what happened	OrderPlaced, OrderRefunded, OrderDelivered
PlaceOrder	Imperative mood (command, not event)	OrderPlaced
DoPayment	Command, not event; uses 'Do' prefix	PaymentReceived, PaymentProcessed
UserModified	Too vague; what was modified?	ProfileUpdated, PasswordChanged, EmailVerified
OrderStatusChanged	Hides the specific transition	OrderConfirmed, OrderShipped, OrderCancelled
Process	No subject, no specificity	PaymentProcessed, RefundProcessed
OrderCreatedEvent	'Event' suffix is redundant	OrderPlaced (or OrderCreated)

Grammatical Patterns:

Most well-named domain events follow one of these patterns:

SubjectVerbed: OrderPlaced, PaymentReceived, AccountLocked
SubjectAttributeChanged: OrderStatusChanged (if status is truly the concept), ProfilePhotoUpdated
NounVerbed: ShipmentDispatched, InvoiceSent, ContractSigned

The first pattern is most common and generally preferred for its clarity.

The Business Narrative Test

Read your events as a story: 'An OrderPlaced occurred for customer 123. Then a PaymentReceived was recorded. Finally, the order was ShipmentDispatched.' If this sounds natural to a domain expert, your naming is on track. If it sounds like database operations, reconsider.

Event Granularity

One of the most important naming decisions is choosing the right level of granularity. Should you have one OrderUpdated event or multiple specific events like OrderShipped, OrderCancelled, OrderAddressChanged?

Coarse-Grained Events

•Example: OrderUpdated, AccountModified
•Fewer event types to maintain
•Consumers must parse payload to understand what changed
•Difficult to subscribe to specific occurrences
•Leads to complex conditional logic in handlers
•Business meaning is hidden in payload

Fine-Grained Events

•Example: OrderShipped, OrderCancelled, OrderAddressChanged
•More event types, but each is clear
•Event type alone tells you what happened
•Consumers subscribe to exactly what they need
•Handler logic is simple and focused
•Business meaning is explicit in the name

Recommendation: Favor fine-grained events

Fine-grained events have significant advantages:

Explicit semantics: OrderCancelled is immediately clear; OrderUpdated with {status: 'CANCELLED'} requires interpretation.
Selective subscription: An email service might care about OrderShipped but not OrderAddressChanged. Fine-grained events enable precise subscriptions.
Simpler handlers: Each handler focuses on one occurrence type, reducing complexity.
Better for event sourcing: Specific events reconstruct state more clearly than generic 'something changed' events.
Cleaner audit trails: 'AccountLocked due to fraud detection' is more informative than 'Account updated'.

The exception: Sometimes a domain genuinely has a single 'thing that happened' with multiple effects. In such cases, one event is appropriate. But be suspicious if you're reaching for generic names—it often indicates missing domain understanding.

GranularityExample.ts
TypeScript
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
// ❌ COARSE-GRAINED: Generic event hides meaning
class OrderUpdated {
    constructor(
        readonly eventId: string,
        readonly occurredAt: Date,
        readonly orderId: string,
        readonly changeType: string,  // 'STATUS_CHANGE' | 'ITEM_ADDED' | 'ADDRESS_UPDATED'
        readonly previousValue: unknown,
        readonly newValue: unknown,
    ) {}
}
 
// Handler becomes complex:
function handleOrderUpdated(event: OrderUpdated) {
    switch (event.changeType) {
        case 'STATUS_CHANGE':
            if (event.newValue === 'SHIPPED') {
                // handle shipping...
            } else if (event.newValue === 'CANCELLED') {
                // handle cancellation...
            }
            break;
        case 'ITEM_ADDED':
            // different handling...
            break;
        // ... more cases
    }
}
 
// ✅ FINE-GRAINED: Each event is explicit
class OrderShipped implements DomainEvent {
    readonly eventType = 'OrderShipped';
    constructor(
        readonly eventId: string,
        readonly occurredAt: Date,
        readonly orderId: string,
        readonly shipmentId: string,
        readonly trackingNumber: string,
        readonly carrier: string,
    ) {}
}
 
class OrderCancelled implements DomainEvent {
    readonly eventType = 'OrderCancelled';
    constructor(
        readonly eventId: string,
        readonly occurredAt: Date,
        readonly orderId: string,
        readonly reason: CancellationReason,
        readonly cancelledBy: string,
    ) {}
}
 
class OrderItemAdded implements DomainEvent {
    readonly eventType = 'OrderItemAdded';
    constructor(
        readonly eventId: string,
        readonly occurredAt: Date,
        readonly orderId: string,
        readonly productId: string,
        readonly quantity: number,
        readonly unitPrice: Money,
    ) {}
}
 
// Handlers are simple and focused:
function handleOrderShipped(event: OrderShipped) {
    notificationService.sendShippingEmail({
        orderId: event.orderId,
        trackingNumber: event.trackingNumber,
        carrier: event.carrier,
    });
}
 
function handleOrderCancelled(event: OrderCancelled) {
    inventoryService.releaseReservedStock(event.orderId);
    paymentService.initiateRefund(event.orderId);
}

Event Structure and Metadata

Every domain event needs certain metadata for identification, ordering, versioning, and traceability. A well-structured event separates these concerns into clear sections.

Essential Event Metadata

•Event ID — Unique identifier for this specific event instance. Enables deduplication, correlation, and tracking.
•Event Type — Discriminator for event routing and deserialization. Usually matches the class name.
•Occurred At — When the event happened in the domain (not when it was persisted or published).
•Event Version — Schema version for evolution. Critical when consumers may be at different versions.
•Aggregate ID — Identifier of the aggregate that raised this event. Links events to their source.
•Aggregate Type — Type of aggregate (e.g., 'Order', 'Account'). Useful for event store partitioning.
•Sequence Number — Position in the aggregate's event stream. Ensures ordering within an aggregate.
•Correlation ID — Links events that are part of the same business transaction or workflow.
•Causation ID — ID of the command or event that caused this event. Builds causal chains.

EventStructure.ts
TypeScript
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
/**
 * Base interface for all domain events with essential metadata.
 * This interface ensures consistency across all events in the system.
 */
interface DomainEventMetadata {
    /** Unique identifier for this event instance */
    readonly eventId: string;
    
    /** Type discriminator for routing and deserialization */
    readonly eventType: string;
    
    /** When this event occurred in the domain */
    readonly occurredAt: Date;
    
    /** Schema version for handling evolution */
    readonly eventVersion: number;
    
    /** ID of the aggregate that raised this event */
    readonly aggregateId: string;
    
    /** Type of the aggregate (for partitioning/routing) */
    readonly aggregateType: string;
    
    /** Position in aggregate's event stream (optional but recommended) */
    readonly sequenceNumber?: number;
    
    /** Links events in the same business transaction */
    readonly correlationId?: string;
    
    /** ID of the command/event that caused this one */
    readonly causationId?: string;
}
 
/**
 * Full domain event structure separating metadata from payload.
 */
interface DomainEvent<TPayload> extends DomainEventMetadata {
    /** The business-specific data for this event */
    readonly payload: TPayload;
}
 
/**
 * Payload for OrderPlaced event - the business-specific content
 */
interface OrderPlacedPayload {
    readonly customerId: string;
    readonly orderNumber: string;
    readonly items: ReadonlyArray<OrderLineItem>;
    readonly totalAmount: Money;
    readonly shippingAddress: Address;
    readonly customerEmail: string;
}
 
/**
 * Factory function to create events with consistent metadata
 */
function createOrderPlacedEvent(
    aggregateId: string,
    payload: OrderPlacedPayload,
    context: EventContext,
): DomainEvent<OrderPlacedPayload> {
    return {
        // Event identity
        eventId: generateUUID(),
        eventType: 'OrderPlaced',
        eventVersion: 1,
        occurredAt: new Date(),
        
        // Aggregate context
        aggregateId,
        aggregateType: 'Order',
        sequenceNumber: context.nextSequenceNumber,
        
        // Tracing context
        correlationId: context.correlationId,
        causationId: context.commandId,
        
        // Business payload
        payload,
    };
}
 
/**
 * Alternative approach: Event class with metadata built-in
 */
abstract class BaseDomainEvent implements DomainEventMetadata {
    readonly eventId: string;
    readonly occurredAt: Date;
    readonly correlationId?: string;
    readonly causationId?: string;
    
    abstract readonly eventType: string;
    abstract readonly eventVersion: number;
    abstract readonly aggregateId: string;
    abstract readonly aggregateType: string;
    
    constructor(context?: EventContext) {
        this.eventId = generateUUID();
        this.occurredAt = new Date();
        this.correlationId = context?.correlationId;
        this.causationId = context?.causationId;
    }
}
 
class OrderPlaced extends BaseDomainEvent {
    readonly eventType = 'OrderPlaced';
    readonly eventVersion = 1;
    readonly aggregateType = 'Order';
    
    constructor(
        readonly aggregateId: string,
        readonly customerId: string,
        readonly orderNumber: string,
        readonly items: ReadonlyArray<OrderLineItem>,
        readonly totalAmount: Money,
        readonly shippingAddress: Address,
        readonly customerEmail: string,
        context?: EventContext,
    ) {
        super(context);
    }
}

Correlation vs Causation

Correlation ID links all events in a business transaction (e.g., everything stemming from one API request). Causation ID shows the direct cause of this specific event (the command that triggered it, or another event in a saga). Both are valuable for debugging distributed systems.

Correlation and Causation Chains

In distributed systems, a single user action can trigger cascading events across multiple services. Tracking these chains is essential for debugging, auditing, and understanding system behavior.

Scenario: Customer places an order → Payment is processed → Inventory is reserved → Confirmation email is sent → Analytics are updated

When something goes wrong (email wasn't sent), you need to trace backward through the chain. Correlation and causation IDs make this possible.

TraceabilityChain.ts
TypeScript
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
/**
 * Example: Tracing a purchase flow through events
 * 
 * All events share the same correlationId (the purchase transaction).
 * Each event's causationId points to what directly triggered it.
 */
 
// 1. Customer places order (initiated by PlaceOrderCommand)
const orderPlaced: DomainEvent = {
    eventId: 'evt-001',
    eventType: 'OrderPlaced',
    occurredAt: new Date('2024-01-15T10:00:00Z'),
    aggregateId: 'order-123',
    aggregateType: 'Order',
    correlationId: 'txn-abc',    // The purchase transaction
    causationId: 'cmd-place-001', // PlaceOrderCommand
    // ... payload
};
 
// 2. Payment service processes payment (triggered by OrderPlaced)
const paymentReceived: DomainEvent = {
    eventId: 'evt-002',
    eventType: 'PaymentReceived',
    occurredAt: new Date('2024-01-15T10:00:05Z'),
    aggregateId: 'payment-456',
    aggregateType: 'Payment',
    correlationId: 'txn-abc',    // Same transaction
    causationId: 'evt-001',      // Caused by OrderPlaced
    // ... payload
};
 
// 3. Inventory service reserves stock (triggered by OrderPlaced)
const inventoryReserved: DomainEvent = {
    eventId: 'evt-003',
    eventType: 'InventoryReserved',
    occurredAt: new Date('2024-01-15T10:00:02Z'),
    aggregateId: 'product-789',
    aggregateType: 'Inventory',
    correlationId: 'txn-abc',    // Same transaction
    causationId: 'evt-001',      // Also caused by OrderPlaced
    // ... payload
};
 
// 4. Email sent after payment confirmed (triggered by PaymentReceived)
const confirmationEmailSent: DomainEvent = {
    eventId: 'evt-004',
    eventType: 'OrderConfirmationEmailSent',
    occurredAt: new Date('2024-01-15T10:00:07Z'),
    aggregateId: 'order-123',
    aggregateType: 'Notification',
    correlationId: 'txn-abc',    // Same transaction
    causationId: 'evt-002',      // Caused by PaymentReceived
    // ... payload
};
 
/**
 * Building the causal chain for debugging:
 * 
 * txn-abc (correlationId) links all events in this purchase
 * 
 * Causal chain:
 * cmd-place-001 (PlaceOrderCommand)
 *     └── evt-001 (OrderPlaced)
 *             ├── evt-002 (PaymentReceived)
 *             │       └── evt-004 (ConfirmationEmailSent)
 *             └── evt-003 (InventoryReserved)
 */
 
// Query: Find all events in a transaction
async function findEventsByCorrelation(correlationId: string): Promise<DomainEvent[]> {
    return eventStore.query({ correlationId });
}
 
// Query: Build causal tree for debugging
async function buildCausalTree(eventId: string): Promise<CausalTree> {
    const root = await eventStore.findById(eventId);
    const children = await eventStore.query({ causationId: eventId });
    
    return {
        event: root,
        children: await Promise.all(
            children.map(child => buildCausalTree(child.eventId))
        ),
    };
}

Debugging with Traces

When a customer reports an issue, find the correlation ID from any event or log. Query all events with that correlation ID. You now have the complete story of that business transaction across all services.

Event Versioning and Schema Evolution

Events are immutable, but event schemas evolve. New fields are added. Old fields become obsolete. Payload structures change. How do you handle this evolution while maintaining compatibility with historical events and diverse consumers?

Event Versioning Strategies

•Weak Schema (Optional Fields) — All new fields are optional. Consumers handle missing fields gracefully. Simplest approach but can lead to ambiguity over time.
•Version Numbers — Each event carries a version number. Consumers check the version and deserialize accordingly. Most explicit approach.
•Event Upcasting — Transform old events to new format on read. Historical data stays unchanged; consumers see current schema.
•Multiple Event Types — Create new event type (OrderPlacedV2) when changes are breaking. Old and new can coexist.

EventVersioning.ts
TypeScript
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
132
133
134
135
136
137
138
139
140
141
142
143
144
/**
 * Strategy 1: Weak Schema with Optional Fields
 * 
 * Add new fields as optional. Consumers handle absence gracefully.
 */
interface OrderPlacedV1 {
    orderId: string;
    customerId: string;
    items: OrderItem[];
    total: Money;
}
 
// Later, we need customer email for notifications
interface OrderPlacedV2 extends OrderPlacedV1 {
    customerEmail?: string;  // Optional for backward compatibility
}
 
// Consumer handles gracefully:
function handleOrderPlaced(event: OrderPlacedV2) {
    if (event.customerEmail) {
        sendConfirmation(event.customerEmail);
    } else {
        // Fallback: fetch email from customer service
        const email = await customerService.getEmail(event.customerId);
        sendConfirmation(email);
    }
}
 
/**
 * Strategy 2: Explicit Version Numbers
 * 
 * Version is part of the event, enabling precise handling.
 */
interface OrderPlaced_v1 {
    eventVersion: 1;
    orderId: string;
    customerId: string;
    total: Money;
}
 
interface OrderPlaced_v2 {
    eventVersion: 2;
    orderId: string;
    customerId: string;
    total: Money;
    customerEmail: string;  // Now required
    orderNumber: string;     // New field
}
 
type OrderPlaced = OrderPlaced_v1 | OrderPlaced_v2;
 
function handleOrderPlaced(event: OrderPlaced) {
    switch (event.eventVersion) {
        case 1:
            // Handle v1 format
            return handleV1(event);
        case 2:
            // Handle v2 format with new fields
            return handleV2(event);
        default:
            throw new UnknownEventVersionError(event);
    }
}
 
/**
 * Strategy 3: Event Upcasting
 * 
 * Transform old events to latest format on read.
 * Historical storage is unchanged; consumers see current schema.
 */
interface EventUpcaster<TFrom, TTo> {
    fromVersion: number;
    toVersion: number;
    upcast(event: TFrom): TTo;
}
 
const orderPlacedUpcaster: EventUpcaster<OrderPlaced_v1, OrderPlaced_v2> = {
    fromVersion: 1,
    toVersion: 2,
    upcast(v1: OrderPlaced_v1): OrderPlaced_v2 {
        return {
            eventVersion: 2,
            orderId: v1.orderId,
            customerId: v1.customerId,
            total: v1.total,
            customerEmail: 'unknown@legacy.com',  // Default for legacy
            orderNumber: generateLegacyOrderNumber(v1.orderId),
        };
    },
};
 
// Event store applies upcasters automatically:
class UpcastingEventStore {
    private upcasters: Map<string, EventUpcaster<any, any>[]>;
    
    async loadEvents(aggregateId: string): Promise<DomainEvent[]> {
        const rawEvents = await this.storage.load(aggregateId);
        
        return rawEvents.map(event => this.upcast(event));
    }
    
    private upcast(event: DomainEvent): DomainEvent {
        const chain = this.upcasters.get(event.eventType) || [];
        
        let current = event;
        for (const upcaster of chain) {
            if (current.eventVersion === upcaster.fromVersion) {
                current = upcaster.upcast(current);
            }
        }
        
        return current;
    }
}
 
/**
 * Strategy 4: New Event Types for Breaking Changes
 * 
 * When changes are too significant, create a new event type.
 */
// Original event
class CustomerRegistered implements DomainEvent {
    readonly eventType = 'CustomerRegistered';
    constructor(
        readonly customerId: string,
        readonly email: string,
        readonly name: string,
    ) {}
}
 
// Major restructuring required - create new event
class CustomerRegisteredV2 implements DomainEvent {
    readonly eventType = 'CustomerRegisteredV2';  // New type
    constructor(
        readonly customerId: string,
        readonly email: string,
        readonly firstName: string,  // Name split into parts
        readonly lastName: string,
        readonly phone?: string,     // New optional field
        readonly preferences: CustomerPreferences,
    ) {}
}
 
// Both events can coexist; consumers subscribe to what they need

Breaking Changes

Changing field types, removing required fields, or altering semantic meaning are breaking changes. Use upcasters or new event types. Never modify historical events in storage—this violates immutability and breaks event sourcing.

Event Naming Anti-Patterns

Understanding what not to do is as important as knowing best practices. These anti-patterns frequently appear in codebases and lead to maintenance headaches.

Common Anti-Patterns

•The Mega-Event — One event type with a 'type' or 'action' field that determines behavior. OrderEvent { action: 'PLACED' | 'SHIPPED' | 'CANCELLED' }. This hides meaning in the payload and complicates handling.
•Command Masquerading as Event — CreateOrder, UpdatePayment, DeleteAccount. These are commands (things we want to happen), not events (things that happened). Use past tense.
•Infrastructure Leakage — OrderTableRowInserted, CacheRefreshed, QueueMessagePublished. These expose implementation details. Events should be domain concepts.
•Redundant Suffix — OrderPlacedEvent, PaymentReceivedEvent. The 'Event' suffix adds no value and clutters names. We know they're events by context.
•Unclear Causality — OrderHandled, CustomerProcessed. What does 'handled' or 'processed' mean? Be specific about what happened.
•CRUD Events — OrderCreated, OrderUpdated, OrderDeleted. These mirror database operations, not domain occurrences. What business event does 'updated' represent?
•No Subject — Registered, Approved, Completed. What was registered? What was approved? Always include the subject for clarity.

AntiPatterns.ts
TypeScript
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
// ❌ MEGA-EVENT ANTI-PATTERN
class OrderEvent {
    constructor(
        readonly eventId: string,
        readonly orderId: string,
        readonly action: 'PLACED' | 'SHIPPED' | 'CANCELLED' | 'RETURNED',
        readonly data: unknown,  // Polymorphic payload
    ) {}
}
 
// Every handler must check the action:
function handleOrderEvent(event: OrderEvent) {
    switch (event.action) {
        case 'PLACED':
            // What type is data here? Need to cast...
            const placedData = event.data as PlacedData;
            // ...
            break;
        case 'SHIPPED':
            const shippedData = event.data as ShippedData;
            // ...
            break;
        // complexity grows with each action
    }
}
 
// ✅ CORRECT: Specific event types
class OrderPlaced { /* ... */ }
class OrderShipped { /* ... */ }
class OrderCancelled { /* ... */ }
class OrderReturned { /* ... */ }
 
// ❌ COMMAND MASQUERADING AS EVENT
class CreateOrder {  // Imperative = command
    constructor(
        readonly customerId: string,
        readonly items: Item[],
    ) {}
}
 
// ✅ CORRECT: Past tense = event
class OrderPlaced {
    constructor(
        readonly orderId: string,
        readonly customerId: string,
        readonly items: Item[],
    ) {}
}
 
// ❌ CRUD EVENTS - mirror database, not domain
class OrderCreated { /* ... */ }
class OrderUpdated { /* fields changed */ }
class OrderDeleted { /* ... */ }
 
// ✅ CORRECT: Domain events - describe business occurrences
class OrderPlaced { /* ... */ }
class OrderItemAdded { /* ... */ }
class ShippingAddressChanged { /* ... */ }
class OrderCancelled { /* with reason */ }
 
// ❌ NO SUBJECT
class Approved { /* What was approved? */ }
 
// ✅ CORRECT: Include subject
class LoanApplicationApproved { /* ... */ }
class ExpenseReportApproved { /* ... */ }

Practical Event Design Checklist

Before finalizing any domain event, run through this checklist to ensure it meets quality standards:

Event Design Checklist

•Naming: Is the name in past tense using ubiquitous language?
•Specificity: Does the name clearly indicate what happened without looking at the payload?
•Immutability: Are all fields readonly? No setters or mutation methods?
•Self-Containment: Does it include sufficient context to process without external queries?
•Metadata: Does it have eventId, occurredAt, eventVersion, aggregateId?
•Traceability: Are correlationId and causationId included for distributed tracing?
•Versioning: Is there a plan for schema evolution?
•Domain Relevance: Would a domain expert recognize and care about this event?
•Granularity: Is it specific enough that handlers don't need to inspect nested fields to understand what happened?
•Serializability: Can it be serialized to JSON/Protobuf without losing information?

Event Storming Validation

In Event Storming workshops, domain experts write events on orange sticky notes. If they naturally write 'Order Placed', 'Payment Failed', 'Shipment Delayed'—you have good event names. If they struggle to express something concisely, the underlying domain model may need refinement.

Summary: Naming and Structure Best Practices

Let's consolidate the key principles for event naming and structure:

Key Takeaways

•Past tense, ubiquitous language — Events describe what happened using domain vocabulary: OrderPlaced, PaymentReceived.
•Be specific over generic — Prefer fine-grained events like OrderShipped over generic OrderUpdated.
•Essential metadata — Every event needs eventId, occurredAt, eventVersion, and aggregate context.
•Enable tracing — Include correlationId and causationId for distributed debugging.
•Plan for versioning — Choose a schema evolution strategy: optional fields, upcasting, or new event types.
•Avoid anti-patterns — No mega-events, no commands as events, no CRUD events, no infrastructure leakage.
•Validate with domain experts — If they can't understand your event names, redesign them.

What's next:

Now that we know how to name and structure events, we'll explore the mechanics of raising and handling events—how events flow from their origin in aggregates through dispatchers to handlers, and the different patterns for managing this lifecycle.

Page Complete

You now have a comprehensive understanding of event naming conventions, structural patterns, versioning strategies, and anti-patterns to avoid. These principles will guide you in creating clear, maintainable, and evolvable domain events.

2 / 4

Loading learning content...

System Design (LLD)Domain Events

Domain Events

LevelIntermediate

Duration60 mins

TopicDomain Events

2 / 4

Event Naming and Structure

The Language of Your Events

More than aesthetics, consistent event design enables:

Schema evolution without breaking consumers
Cross-team understanding without extensive documentation
Tooling and automation that works across all events
Long-term maintainability as systems grow

This page establishes the naming conventions and structural patterns that make your domain events a reliable foundation for your architecture.

What You Will Learn

Naming Conventions

Event Naming Principles

•Use Past Tense — Events describe something that happened: OrderPlaced, not PlaceOrder. Past tense emphasizes that events are historical facts, not commands or requests.
•Use Ubiquitous Language — Names should come from the domain vocabulary that business experts use. ShipmentDispatched is better than OrderFulfillmentProcessExecuted.
•Be Specific, Not Generic — Avoid generic names like OrderUpdated or EntityChanged. These lack semantic meaning. What specifically happened? OrderShipped, OrderCancelled, PriceAdjusted.
•Include the Subject — The event name should include what was affected: Order + Placed = OrderPlaced. This makes the event self-documenting.
•Avoid Technical Terms — Events are part of the domain model, not infrastructure. Avoid names like OrderRecordInserted or OrderRowCreated.
•Consider the Reader — Names should be understandable to someone unfamiliar with your specific implementation. Would a new team member or domain expert understand what this event means?

Event Naming: Good vs Poor Examples
Poor Name	Why It's Poor	Better Name
OrderUpdated	What update? Status? Items? Address?	OrderShipped, OrderItemRemoved, ShippingAddressChanged
OrderEvent	Tells nothing about what happened	OrderPlaced, OrderRefunded, OrderDelivered
PlaceOrder	Imperative mood (command, not event)	OrderPlaced
DoPayment	Command, not event; uses 'Do' prefix	PaymentReceived, PaymentProcessed
UserModified	Too vague; what was modified?	ProfileUpdated, PasswordChanged, EmailVerified
OrderStatusChanged	Hides the specific transition	OrderConfirmed, OrderShipped, OrderCancelled
Process	No subject, no specificity	PaymentProcessed, RefundProcessed
OrderCreatedEvent	'Event' suffix is redundant	OrderPlaced (or OrderCreated)

Grammatical Patterns:

Most well-named domain events follow one of these patterns:

SubjectVerbed: OrderPlaced, PaymentReceived, AccountLocked
SubjectAttributeChanged: OrderStatusChanged (if status is truly the concept), ProfilePhotoUpdated
NounVerbed: ShipmentDispatched, InvoiceSent, ContractSigned

The first pattern is most common and generally preferred for its clarity.

The Business Narrative Test

Event Granularity

Coarse-Grained Events

•Example: OrderUpdated, AccountModified
•Fewer event types to maintain
•Consumers must parse payload to understand what changed
•Difficult to subscribe to specific occurrences
•Leads to complex conditional logic in handlers
•Business meaning is hidden in payload

Fine-Grained Events

•Example: OrderShipped, OrderCancelled, OrderAddressChanged
•More event types, but each is clear
•Event type alone tells you what happened
•Consumers subscribe to exactly what they need
•Handler logic is simple and focused
•Business meaning is explicit in the name

Recommendation: Favor fine-grained events

Fine-grained events have significant advantages:

Explicit semantics: OrderCancelled is immediately clear; OrderUpdated with {status: 'CANCELLED'} requires interpretation.
Selective subscription: An email service might care about OrderShipped but not OrderAddressChanged. Fine-grained events enable precise subscriptions.
Simpler handlers: Each handler focuses on one occurrence type, reducing complexity.
Better for event sourcing: Specific events reconstruct state more clearly than generic 'something changed' events.
Cleaner audit trails: 'AccountLocked due to fraud detection' is more informative than 'Account updated'.

GranularityExample.ts
TypeScript
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
// ❌ COARSE-GRAINED: Generic event hides meaning
class OrderUpdated {
    constructor(
        readonly eventId: string,
        readonly occurredAt: Date,
        readonly orderId: string,
        readonly changeType: string,  // 'STATUS_CHANGE' | 'ITEM_ADDED' | 'ADDRESS_UPDATED'
        readonly previousValue: unknown,
        readonly newValue: unknown,
    ) {}
}
 
// Handler becomes complex:
function handleOrderUpdated(event: OrderUpdated) {
    switch (event.changeType) {
        case 'STATUS_CHANGE':
            if (event.newValue === 'SHIPPED') {
                // handle shipping...
            } else if (event.newValue === 'CANCELLED') {
                // handle cancellation...
            }
            break;
        case 'ITEM_ADDED':
            // different handling...
            break;
        // ... more cases
    }
}
 
// ✅ FINE-GRAINED: Each event is explicit
class OrderShipped implements DomainEvent {
    readonly eventType = 'OrderShipped';
    constructor(
        readonly eventId: string,
        readonly occurredAt: Date,
        readonly orderId: string,
        readonly shipmentId: string,
        readonly trackingNumber: string,
        readonly carrier: string,
    ) {}
}
 
class OrderCancelled implements DomainEvent {
    readonly eventType = 'OrderCancelled';
    constructor(
        readonly eventId: string,
        readonly occurredAt: Date,
        readonly orderId: string,
        readonly reason: CancellationReason,
        readonly cancelledBy: string,
    ) {}
}
 
class OrderItemAdded implements DomainEvent {
    readonly eventType = 'OrderItemAdded';
    constructor(
        readonly eventId: string,
        readonly occurredAt: Date,
        readonly orderId: string,
        readonly productId: string,
        readonly quantity: number,
        readonly unitPrice: Money,
    ) {}
}
 
// Handlers are simple and focused:
function handleOrderShipped(event: OrderShipped) {
    notificationService.sendShippingEmail({
        orderId: event.orderId,
        trackingNumber: event.trackingNumber,
        carrier: event.carrier,
    });
}
 
function handleOrderCancelled(event: OrderCancelled) {
    inventoryService.releaseReservedStock(event.orderId);
    paymentService.initiateRefund(event.orderId);
}

Event Structure and Metadata

Every domain event needs certain metadata for identification, ordering, versioning, and traceability. A well-structured event separates these concerns into clear sections.

Essential Event Metadata

•Event ID — Unique identifier for this specific event instance. Enables deduplication, correlation, and tracking.
•Event Type — Discriminator for event routing and deserialization. Usually matches the class name.
•Occurred At — When the event happened in the domain (not when it was persisted or published).
•Event Version — Schema version for evolution. Critical when consumers may be at different versions.
•Aggregate ID — Identifier of the aggregate that raised this event. Links events to their source.
•Aggregate Type — Type of aggregate (e.g., 'Order', 'Account'). Useful for event store partitioning.
•Sequence Number — Position in the aggregate's event stream. Ensures ordering within an aggregate.
•Correlation ID — Links events that are part of the same business transaction or workflow.
•Causation ID — ID of the command or event that caused this event. Builds causal chains.

EventStructure.ts
TypeScript
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
/**
 * Base interface for all domain events with essential metadata.
 * This interface ensures consistency across all events in the system.
 */
interface DomainEventMetadata {
    /** Unique identifier for this event instance */
    readonly eventId: string;
    
    /** Type discriminator for routing and deserialization */
    readonly eventType: string;
    
    /** When this event occurred in the domain */
    readonly occurredAt: Date;
    
    /** Schema version for handling evolution */
    readonly eventVersion: number;
    
    /** ID of the aggregate that raised this event */
    readonly aggregateId: string;
    
    /** Type of the aggregate (for partitioning/routing) */
    readonly aggregateType: string;
    
    /** Position in aggregate's event stream (optional but recommended) */
    readonly sequenceNumber?: number;
    
    /** Links events in the same business transaction */
    readonly correlationId?: string;
    
    /** ID of the command/event that caused this one */
    readonly causationId?: string;
}
 
/**
 * Full domain event structure separating metadata from payload.
 */
interface DomainEvent<TPayload> extends DomainEventMetadata {
    /** The business-specific data for this event */
    readonly payload: TPayload;
}
 
/**
 * Payload for OrderPlaced event - the business-specific content
 */
interface OrderPlacedPayload {
    readonly customerId: string;
    readonly orderNumber: string;
    readonly items: ReadonlyArray<OrderLineItem>;
    readonly totalAmount: Money;
    readonly shippingAddress: Address;
    readonly customerEmail: string;
}
 
/**
 * Factory function to create events with consistent metadata
 */
function createOrderPlacedEvent(
    aggregateId: string,
    payload: OrderPlacedPayload,
    context: EventContext,
): DomainEvent<OrderPlacedPayload> {
    return {
        // Event identity
        eventId: generateUUID(),
        eventType: 'OrderPlaced',
        eventVersion: 1,
        occurredAt: new Date(),
        
        // Aggregate context
        aggregateId,
        aggregateType: 'Order',
        sequenceNumber: context.nextSequenceNumber,
        
        // Tracing context
        correlationId: context.correlationId,
        causationId: context.commandId,
        
        // Business payload
        payload,
    };
}
 
/**
 * Alternative approach: Event class with metadata built-in
 */
abstract class BaseDomainEvent implements DomainEventMetadata {
    readonly eventId: string;
    readonly occurredAt: Date;
    readonly correlationId?: string;
    readonly causationId?: string;
    
    abstract readonly eventType: string;
    abstract readonly eventVersion: number;
    abstract readonly aggregateId: string;
    abstract readonly aggregateType: string;
    
    constructor(context?: EventContext) {
        this.eventId = generateUUID();
        this.occurredAt = new Date();
        this.correlationId = context?.correlationId;
        this.causationId = context?.causationId;
    }
}
 
class OrderPlaced extends BaseDomainEvent {
    readonly eventType = 'OrderPlaced';
    readonly eventVersion = 1;
    readonly aggregateType = 'Order';
    
    constructor(
        readonly aggregateId: string,
        readonly customerId: string,
        readonly orderNumber: string,
        readonly items: ReadonlyArray<OrderLineItem>,
        readonly totalAmount: Money,
        readonly shippingAddress: Address,
        readonly customerEmail: string,
        context?: EventContext,
    ) {
        super(context);
    }
}

Correlation vs Causation

Correlation and Causation Chains

In distributed systems, a single user action can trigger cascading events across multiple services. Tracking these chains is essential for debugging, auditing, and understanding system behavior.

Scenario: Customer places an order → Payment is processed → Inventory is reserved → Confirmation email is sent → Analytics are updated

When something goes wrong (email wasn't sent), you need to trace backward through the chain. Correlation and causation IDs make this possible.

TraceabilityChain.ts
TypeScript
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
/**
 * Example: Tracing a purchase flow through events
 * 
 * All events share the same correlationId (the purchase transaction).
 * Each event's causationId points to what directly triggered it.
 */
 
// 1. Customer places order (initiated by PlaceOrderCommand)
const orderPlaced: DomainEvent = {
    eventId: 'evt-001',
    eventType: 'OrderPlaced',
    occurredAt: new Date('2024-01-15T10:00:00Z'),
    aggregateId: 'order-123',
    aggregateType: 'Order',
    correlationId: 'txn-abc',    // The purchase transaction
    causationId: 'cmd-place-001', // PlaceOrderCommand
    // ... payload
};
 
// 2. Payment service processes payment (triggered by OrderPlaced)
const paymentReceived: DomainEvent = {
    eventId: 'evt-002',
    eventType: 'PaymentReceived',
    occurredAt: new Date('2024-01-15T10:00:05Z'),
    aggregateId: 'payment-456',
    aggregateType: 'Payment',
    correlationId: 'txn-abc',    // Same transaction
    causationId: 'evt-001',      // Caused by OrderPlaced
    // ... payload
};
 
// 3. Inventory service reserves stock (triggered by OrderPlaced)
const inventoryReserved: DomainEvent = {
    eventId: 'evt-003',
    eventType: 'InventoryReserved',
    occurredAt: new Date('2024-01-15T10:00:02Z'),
    aggregateId: 'product-789',
    aggregateType: 'Inventory',
    correlationId: 'txn-abc',    // Same transaction
    causationId: 'evt-001',      // Also caused by OrderPlaced
    // ... payload
};
 
// 4. Email sent after payment confirmed (triggered by PaymentReceived)
const confirmationEmailSent: DomainEvent = {
    eventId: 'evt-004',
    eventType: 'OrderConfirmationEmailSent',
    occurredAt: new Date('2024-01-15T10:00:07Z'),
    aggregateId: 'order-123',
    aggregateType: 'Notification',
    correlationId: 'txn-abc',    // Same transaction
    causationId: 'evt-002',      // Caused by PaymentReceived
    // ... payload
};
 
/**
 * Building the causal chain for debugging:
 * 
 * txn-abc (correlationId) links all events in this purchase
 * 
 * Causal chain:
 * cmd-place-001 (PlaceOrderCommand)
 *     └── evt-001 (OrderPlaced)
 *             ├── evt-002 (PaymentReceived)
 *             │       └── evt-004 (ConfirmationEmailSent)
 *             └── evt-003 (InventoryReserved)
 */
 
// Query: Find all events in a transaction
async function findEventsByCorrelation(correlationId: string): Promise<DomainEvent[]> {
    return eventStore.query({ correlationId });
}
 
// Query: Build causal tree for debugging
async function buildCausalTree(eventId: string): Promise<CausalTree> {
    const root = await eventStore.findById(eventId);
    const children = await eventStore.query({ causationId: eventId });
    
    return {
        event: root,
        children: await Promise.all(
            children.map(child => buildCausalTree(child.eventId))
        ),
    };
}

Debugging with Traces

Event Versioning and Schema Evolution

Event Versioning Strategies

•Weak Schema (Optional Fields) — All new fields are optional. Consumers handle missing fields gracefully. Simplest approach but can lead to ambiguity over time.
•Version Numbers — Each event carries a version number. Consumers check the version and deserialize accordingly. Most explicit approach.
•Event Upcasting — Transform old events to new format on read. Historical data stays unchanged; consumers see current schema.
•Multiple Event Types — Create new event type (OrderPlacedV2) when changes are breaking. Old and new can coexist.

EventVersioning.ts
TypeScript
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
132
133
134
135
136
137
138
139
140
141
142
143
144
/**
 * Strategy 1: Weak Schema with Optional Fields
 * 
 * Add new fields as optional. Consumers handle absence gracefully.
 */
interface OrderPlacedV1 {
    orderId: string;
    customerId: string;
    items: OrderItem[];
    total: Money;
}
 
// Later, we need customer email for notifications
interface OrderPlacedV2 extends OrderPlacedV1 {
    customerEmail?: string;  // Optional for backward compatibility
}
 
// Consumer handles gracefully:
function handleOrderPlaced(event: OrderPlacedV2) {
    if (event.customerEmail) {
        sendConfirmation(event.customerEmail);
    } else {
        // Fallback: fetch email from customer service
        const email = await customerService.getEmail(event.customerId);
        sendConfirmation(email);
    }
}
 
/**
 * Strategy 2: Explicit Version Numbers
 * 
 * Version is part of the event, enabling precise handling.
 */
interface OrderPlaced_v1 {
    eventVersion: 1;
    orderId: string;
    customerId: string;
    total: Money;
}
 
interface OrderPlaced_v2 {
    eventVersion: 2;
    orderId: string;
    customerId: string;
    total: Money;
    customerEmail: string;  // Now required
    orderNumber: string;     // New field
}
 
type OrderPlaced = OrderPlaced_v1 | OrderPlaced_v2;
 
function handleOrderPlaced(event: OrderPlaced) {
    switch (event.eventVersion) {
        case 1:
            // Handle v1 format
            return handleV1(event);
        case 2:
            // Handle v2 format with new fields
            return handleV2(event);
        default:
            throw new UnknownEventVersionError(event);
    }
}
 
/**
 * Strategy 3: Event Upcasting
 * 
 * Transform old events to latest format on read.
 * Historical storage is unchanged; consumers see current schema.
 */
interface EventUpcaster<TFrom, TTo> {
    fromVersion: number;
    toVersion: number;
    upcast(event: TFrom): TTo;
}
 
const orderPlacedUpcaster: EventUpcaster<OrderPlaced_v1, OrderPlaced_v2> = {
    fromVersion: 1,
    toVersion: 2,
    upcast(v1: OrderPlaced_v1): OrderPlaced_v2 {
        return {
            eventVersion: 2,
            orderId: v1.orderId,
            customerId: v1.customerId,
            total: v1.total,
            customerEmail: 'unknown@legacy.com',  // Default for legacy
            orderNumber: generateLegacyOrderNumber(v1.orderId),
        };
    },
};
 
// Event store applies upcasters automatically:
class UpcastingEventStore {
    private upcasters: Map<string, EventUpcaster<any, any>[]>;
    
    async loadEvents(aggregateId: string): Promise<DomainEvent[]> {
        const rawEvents = await this.storage.load(aggregateId);
        
        return rawEvents.map(event => this.upcast(event));
    }
    
    private upcast(event: DomainEvent): DomainEvent {
        const chain = this.upcasters.get(event.eventType) || [];
        
        let current = event;
        for (const upcaster of chain) {
            if (current.eventVersion === upcaster.fromVersion) {
                current = upcaster.upcast(current);
            }
        }
        
        return current;
    }
}
 
/**
 * Strategy 4: New Event Types for Breaking Changes
 * 
 * When changes are too significant, create a new event type.
 */
// Original event
class CustomerRegistered implements DomainEvent {
    readonly eventType = 'CustomerRegistered';
    constructor(
        readonly customerId: string,
        readonly email: string,
        readonly name: string,
    ) {}
}
 
// Major restructuring required - create new event
class CustomerRegisteredV2 implements DomainEvent {
    readonly eventType = 'CustomerRegisteredV2';  // New type
    constructor(
        readonly customerId: string,
        readonly email: string,
        readonly firstName: string,  // Name split into parts
        readonly lastName: string,
        readonly phone?: string,     // New optional field
        readonly preferences: CustomerPreferences,
    ) {}
}
 
// Both events can coexist; consumers subscribe to what they need

Breaking Changes

Event Naming Anti-Patterns

Understanding what not to do is as important as knowing best practices. These anti-patterns frequently appear in codebases and lead to maintenance headaches.

Common Anti-Patterns

•The Mega-Event — One event type with a 'type' or 'action' field that determines behavior. OrderEvent { action: 'PLACED' | 'SHIPPED' | 'CANCELLED' }. This hides meaning in the payload and complicates handling.
•Command Masquerading as Event — CreateOrder, UpdatePayment, DeleteAccount. These are commands (things we want to happen), not events (things that happened). Use past tense.
•Infrastructure Leakage — OrderTableRowInserted, CacheRefreshed, QueueMessagePublished. These expose implementation details. Events should be domain concepts.
•Redundant Suffix — OrderPlacedEvent, PaymentReceivedEvent. The 'Event' suffix adds no value and clutters names. We know they're events by context.
•Unclear Causality — OrderHandled, CustomerProcessed. What does 'handled' or 'processed' mean? Be specific about what happened.
•CRUD Events — OrderCreated, OrderUpdated, OrderDeleted. These mirror database operations, not domain occurrences. What business event does 'updated' represent?
•No Subject — Registered, Approved, Completed. What was registered? What was approved? Always include the subject for clarity.

AntiPatterns.ts
TypeScript
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
// ❌ MEGA-EVENT ANTI-PATTERN
class OrderEvent {
    constructor(
        readonly eventId: string,
        readonly orderId: string,
        readonly action: 'PLACED' | 'SHIPPED' | 'CANCELLED' | 'RETURNED',
        readonly data: unknown,  // Polymorphic payload
    ) {}
}
 
// Every handler must check the action:
function handleOrderEvent(event: OrderEvent) {
    switch (event.action) {
        case 'PLACED':
            // What type is data here? Need to cast...
            const placedData = event.data as PlacedData;
            // ...
            break;
        case 'SHIPPED':
            const shippedData = event.data as ShippedData;
            // ...
            break;
        // complexity grows with each action
    }
}
 
// ✅ CORRECT: Specific event types
class OrderPlaced { /* ... */ }
class OrderShipped { /* ... */ }
class OrderCancelled { /* ... */ }
class OrderReturned { /* ... */ }
 
// ❌ COMMAND MASQUERADING AS EVENT
class CreateOrder {  // Imperative = command
    constructor(
        readonly customerId: string,
        readonly items: Item[],
    ) {}
}
 
// ✅ CORRECT: Past tense = event
class OrderPlaced {
    constructor(
        readonly orderId: string,
        readonly customerId: string,
        readonly items: Item[],
    ) {}
}
 
// ❌ CRUD EVENTS - mirror database, not domain
class OrderCreated { /* ... */ }
class OrderUpdated { /* fields changed */ }
class OrderDeleted { /* ... */ }
 
// ✅ CORRECT: Domain events - describe business occurrences
class OrderPlaced { /* ... */ }
class OrderItemAdded { /* ... */ }
class ShippingAddressChanged { /* ... */ }
class OrderCancelled { /* with reason */ }
 
// ❌ NO SUBJECT
class Approved { /* What was approved? */ }
 
// ✅ CORRECT: Include subject
class LoanApplicationApproved { /* ... */ }
class ExpenseReportApproved { /* ... */ }

Practical Event Design Checklist

Before finalizing any domain event, run through this checklist to ensure it meets quality standards:

Event Design Checklist

•Naming: Is the name in past tense using ubiquitous language?
•Specificity: Does the name clearly indicate what happened without looking at the payload?
•Immutability: Are all fields readonly? No setters or mutation methods?
•Self-Containment: Does it include sufficient context to process without external queries?
•Metadata: Does it have eventId, occurredAt, eventVersion, aggregateId?
•Traceability: Are correlationId and causationId included for distributed tracing?
•Versioning: Is there a plan for schema evolution?
•Domain Relevance: Would a domain expert recognize and care about this event?
•Granularity: Is it specific enough that handlers don't need to inspect nested fields to understand what happened?
•Serializability: Can it be serialized to JSON/Protobuf without losing information?

Event Storming Validation

Summary: Naming and Structure Best Practices

Let's consolidate the key principles for event naming and structure:

Key Takeaways

•Past tense, ubiquitous language — Events describe what happened using domain vocabulary: OrderPlaced, PaymentReceived.
•Be specific over generic — Prefer fine-grained events like OrderShipped over generic OrderUpdated.
•Essential metadata — Every event needs eventId, occurredAt, eventVersion, and aggregate context.
•Enable tracing — Include correlationId and causationId for distributed debugging.
•Plan for versioning — Choose a schema evolution strategy: optional fields, upcasting, or new event types.
•Avoid anti-patterns — No mega-events, no commands as events, no CRUD events, no infrastructure leakage.
•Validate with domain experts — If they can't understand your event names, redesign them.

What's next:

Page Complete

2 / 4