Domain Events Vocabulary

These three terms are often confused — understanding the distinction is essential for EDA architecture discussions.

Domain Event — carries full business context:

{
  "type": "OrderShipped",
  "orderId": "ORD-9921",
  "customerId": "C-5512",
  "items": [{"sku": "SKU-01", "qty": 2}],
  "shippedAt": "2025-07-01T10:30Z",
  "carrier": "FedEx",
  "trackingNumber": "FX-78834"
}

Notification (thin event) — carries only an identifier:

{"type": "OrderShipped", "orderId": "ORD-9921"}

Consumers must call back to the source service to get the full data.

Message — the transport envelope; can carry a domain event, command, or query.

Trade-offs:
• Fat event (domain event) — consumers are decoupled; no callback needed; risk of too much data in schema
• Thin event (notification) — less bandwidth; but requires consumers to make additional API calls (chattier)

Key vocabulary:
• Fat event — an event carrying complete domain data
• Thin event / skinny event — an event carrying only an ID (notification style)
• Event-carried state transfer — consumers maintain their own copy of state from fat events

Schema evolution and consumer contracts are critical challenges when you have multiple teams consuming the same events.

Schema evolution problem:
When you publish OrderCancelled and 8 services consume it, any change to the schema can break consumers.

Types of schema changes:

Change type	Compatibility	Example
Add optional field	Backward-compatible ✓	Add cancellationReason
Remove field	Breaking ✗	Remove customerId
Rename field	Breaking ✗	Rename orderId → id
Change type	Breaking ✗	String → Integer

Schema registries (Confluent Schema Registry, AWS Glue) enforce compatibility rules at publish time.

Key vocabulary:
• Schema evolution — planned, controlled changes to event structure over time
• Consumer contract — what a specific consumer depends on in an event (their "minimum required fields")
• Backward-compatible change — a change existing consumers can handle without updating
• Schema registry — a centralised service for storing and validating event schemas

Consistent, domain-aligned event naming is one of the highest-value low-effort improvements in EDA.

Why naming conventions matter:
• Readability — OrderShipped is instantly clear; order_status_change_v2 is not
• Causality — past tense immediately signals this is a fact, not a request or command
• Ubiquitous language alignment — domain experts can read event names in logs, dashboards, and code
• Discoverability — in a schema registry with hundreds of events, consistent naming makes searching tractable

Anti-patterns to avoid:
❌ event_1, event_2 — meaningless
❌ OrderUpdated — too vague (updated how? which fields?)
❌ db_order_table_modified — leaks implementation details
❌ orderPlaced — inconsistent casing

Good naming patterns:
✓ OrderPlaced, OrderShipped, OrderCancelled
✓ PaymentAuthorised, PaymentDeclined, PaymentRefunded
✓ UserRegistered, UserDeactivated, UserPasswordReset

Key vocabulary:
• Ubiquitous language — shared vocabulary between domain experts and developers
• PascalCase — CapitalizeEachWord style (standard for domain events)
• Event taxonomy — structured classification of all events in a domain

The choreography vs orchestration trade-off is one of the most important architectural decisions in EDA.

Choreography:
• Each service listens for events and reacts independently
• OrderPlaced → InventoryService reserves stock → fires InventoryReserved → ShippingService picks it up
• No central coordinator; services are fully decoupled
• ✅ High resilience — no single point of failure
• ✅ Easy to add new consumers without changing existing services
• ❌ Hard to understand the full flow — it lives in no one place
• ❌ Difficult to debug when something goes wrong mid-flow

Orchestration:
• A central process manager (an orchestrator or saga orchestrator) coordinates each step
• "Orchestrator → calls InventoryService → calls ShippingService → calls NotificationService"
• ✅ The flow is explicit and visible in one place
• ✅ Easier to handle errors, retries, and partial failures
• ❌ Tighter coupling — services know about the orchestrator
• ❌ The orchestrator can become a bottleneck

Key vocabulary:
• Choreography — implicit coordination via events; services react independently
• Orchestration — explicit coordination via a central process manager
• Loose coupling — services don't need to know about each other directly

Eventual consistency is not a problem to be eliminated — it is a trade-off to be managed explicitly.

What eventual consistency means in EDA:
When OrderPlaced is published:
• The order service immediately knows the order exists
• The inventory service may not know for 50ms (processing delay)
• The UI dashboard may show stale data for 200ms
• All services will eventually converge to the same view

Strategies for managing eventual consistency:

① UX for async states — show "Order processing…" UI while downstream services catch up
② Idempotent consumers — safe to process the same event twice if it's delivered more than once
③ Compensating events — if a step fails, publish a compensating event to undo previous steps (InventoryReservationCancelled)
④ Explicit consistency boundaries — agree on which operations need strong consistency (payments) vs can tolerate lag (analytics)
⑤ Event ordering guarantees — use Kafka partitions to ensure events for the same entity arrive in order

Key vocabulary:
• Eventual consistency — all services converge to the same state eventually, after a window of time
• Strong consistency — all services see the same state immediately (expensive, synchronous)
• Idempotent consumer — can process the same event multiple times safely
• Compensation — publishing a corrective event to reverse the effect of a previous one