Modeling Events

Learn how to design and model events that accurately represent your domain and business processes.

What is Event Modeling?

Event modeling is the practice of designing events that capture meaningful business occurrences in your domain. Well-modeled events serve as a clear communication tool between technical teams and domain experts, forming the foundation of your event-sourced system.

The goal is to create events that are expressive, complete, and aligned with how your business thinks about and describes state changes in the domain.

Good Event Design
  • OrderShipped - Specific action, past tense
  • PaymentReceived - Clear business meaning
  • CustomerRegistered - Domain language
  • InventoryAdjusted - Intentional and precise
Poor Event Design
  • OrderUpdate - Vague, present tense
  • DataChanged - No business meaning
  • RecordModified - Technical language
  • Thing - Too generic, unclear intent
Event Naming Guidelines

1. Use Past Tense

Events represent facts that have already occurred. Always use past tense to make this clear.

✓ OrderPlaced, ItemAdded, PaymentProcessed
✗ PlaceOrder, AddItem, ProcessPayment

2. Use Domain Language

Event names should use the language of your business domain, not technical jargon.

✓ PatientAdmitted, MedicationPrescribed
✗ RecordCreated, TableUpdated

3. Be Specific

Avoid generic names. Be specific about what happened.

✓ EmailAddressChanged, ShippingAddressUpdated
✗ CustomerUpdated, DataModified

4. Capture Intent

Event names should convey why something happened, not just what changed.

✓ OrderCancelledByCustomer, OrderRefundedDueToDefect
✗ OrderStatusChanged, OrderDeleted
Event Granularity

Deciding the right level of detail for events is crucial. Too coarse and you lose valuable information; too fine and you create complexity.

Fine-Grained Events

Multiple small events for each atomic change

Advantages:
  • • Detailed audit trail
  • • Maximum flexibility
  • • Easy to build varied projections
Disadvantages:
  • • More events to manage
  • • Complex event sequences
  • • Potential performance impact

Coarse-Grained Events

Fewer, more comprehensive events

Advantages:
  • • Simpler event model
  • • Fewer events to process
  • • Easier to understand
Disadvantages:
  • • Loss of granular detail
  • • Less flexibility
  • • May bundle unrelated changes

Finding the Right Balance

Choose granularity based on your business needs. Fine-grained for audit-critical domains (finance, healthcare), coarse-grained for simpler workflows. You can always split coarse events later, but combining fine-grained events retroactively is harder.

Event Content & Structure

Events should contain all necessary information to understand what happened without requiring additional lookups.

Essential Event Properties

Event ID: Unique identifier for this specific event occurrence
Event Type: The name/type of the event (e.g., "OrderPlaced")
Timestamp: When the event occurred
Aggregate ID: The entity this event belongs to
Event Data: The business data describing what changed
Metadata: Correlation IDs, causation IDs, user context

Example: Well-Structured Event

{
  "eventId": "evt_1a2b3c4d",
  "eventType": "OrderPlaced",
  "eventVersion": "1.0",
  "timestamp": "2024-11-12T15:30:00Z",
  "aggregateId": "order_12345",
  "aggregateType": "Order",
  "data": {
    "customerId": "cust_789",
    "orderTotal": 159.99,
    "currency": "USD",
    "items": [
      {
        "productId": "prod_456",
        "productName": "Blue Widget",
        "quantity": 2,
        "unitPrice": 49.99
      },
      {
        "productId": "prod_789",
        "productName": "Red Gadget",
        "quantity": 1,
        "unitPrice": 60.01
      }
    ],
    "shippingAddress": {
      "street": "123 Main St",
      "city": "Springfield",
      "postalCode": "12345",
      "country": "US"
    }
  },
  "metadata": {
    "userId": "user_321",
    "correlationId": "corr_abc123",
    "causationId": "cmd_def456"
  }
}
Common Modeling Pitfalls
  • •
    Events that are too generic: "StateChanged" or "DataUpdated" events provide no business value
  • •
    Including behavior in events: Events should be pure data with no business logic
  • •
    Incomplete event data: Requiring additional queries to understand the event defeats the purpose
  • •
    Mutable references: Storing references to data that might change or be deleted
  • •
    Technical language: Using database or implementation terms instead of domain language
Key Takeaways
  • Events capture business facts in past tense using domain language
  • Choose granularity based on your audit and flexibility requirements
  • Include all necessary context to make events self-contained
  • Event names should clearly communicate what happened and why
  • Collaborate with domain experts to discover the right events