What Is a Domain Event?

A domain event is an immutable record of something the business cares about having happened: OrderPlaced, PaymentReceived, ShipmentDispatched.

Naming rule: always past tense. If you find yourself writing OrderPlacing or PlaceOrder (an imperative), that's a command, not an event.

Worked example — two complete domain events in YAML.

A domain event in our format is just a name (past tense) plus a payload of typed fields — the immutable facts a consumer needs to react:

events:
  - name: OrderPlaced
    payload:
      order_id: string       # the aggregate id
      customer_id: string    # by id only — never the whole Customer
      total: Money           # value object
      occurred_at: datetime

  - name: PaymentReceived
    payload:
      payment_id: string
      order_id: string
      amount: Money
      occurred_at: datetime

Notice:

• Each name is past tense (OrderPlaced, PaymentReceived) — the validator below fails any name that does not end in -ed or -d.
• Payloads carry identifiers and value objects, not whole aggregates.
• occurred_at is the wall-clock time when the fact happened — events are immutable, so this never changes after publication.

Use this as a template for PaymentReceived and ShipmentDispatched in the playground below.