EventsBest Practices

Event Best Practices

Use past-tense fact names

Events describe what happened. Commands belong in actions: (intents).

Never shadow envelope fields

Do not declare type, ts, or entity_id in payload. Use notification_type, created_at, id instead.

Scope names to avoid collisions

Prefix by domain when the same verb applies to multiple entity types: ARTIST_SHOW_ANNOUNCED vs VENUE_SHOW_SCHEDULED.

Version carefully

Adding optional payload fields is usually safe. Removing or retyping fields requires projection and replay planning — see Event Versioning.

Common mistakes

Using imperative names

# Wrong
events:
  FOLLOW_ARTIST:
 
# Correct
events:
  ARTIST_FOLLOWED:

Declaring reserved fields in payload

# Wrong — compiler error
payload:
  type: string
  entity_id: string
  ts: int

Duplicate event names across states

Event names are global. One SHOW_ANNOUNCED per application unless names are domain-scoped.

Next steps

Testing EventsExamples