How to write an event spec

How-To Write specs by level Intermediate 1051009HOWTO-1051009

HOWTO-1051009Write specs by levelIntermediate

This guide shows you how to write a SpecDD event spec for a spec-driven development workflow.

An event spec describes emitted or consumed event and message contracts: domain events, integration events, pub/sub messages, webhook payloads, queue messages, or local event bus entries.

Short answer

Use an event spec for one event or small event family. Define the event name, who emits or consumes it, accepted payload shape, returned or emitted outcome when relevant, handled cases, compatibility expectations, and side effects the event must not trigger.

When to use this guide

Use this guide when:

an event payload is shared across modules or services
producers and consumers need a stable contract
event handling failures are subtle
agents keep changing message shape accidentally
compatibility matters during rollout

Steps

1. Identify the event

Examples:

trip-created.sdd
trip-created.event.sdd
itinerary-updated.event.sdd

Use one spec per important event unless several events are intentionally one small family.

2. Name the event surface

Exposes:
  trip.created event

If the spec is for a consumer, use Handles:

Handles:
  trip.created event

3. Describe the payload

Accepts:
  tripId
  destination
  createdAt

or:

Returns:
  trip.created event payload

Use the section that matches whether the spec consumes or emits the event.

4. Name producers and consumers as context

Depends on:
  TripCreationService

References:
  ../notifications/trip-notification.sdd

References provide context. They do not grant write authority over consumers.

5. Protect compatibility

Must:
  Include tripId in every emitted event.
  Preserve existing payload fields unless a reviewed compatibility change is approved.

Must not:
  Emit booking purchase data.

Event specs should make compatibility risks visible.

6. Add examples

Example: trip created
  event: trip.created
  tripId: trip_123
  destination: Paris

Examples are useful for payload shape.

Complete example

Spec: Trip Created Event

Purpose:
  Notify local consumers that a trip was created.

Owns:
  ./trip-created.event.ts
  ./trip-created.event.test.ts

Exposes:
  trip.created event

Accepts:
  tripId
  destination
  createdAt

Must:
  Include tripId in every emitted event.
  Preserve existing payload fields unless a reviewed compatibility change is approved.

Must not:
  Emit booking purchase data.

Depends on:
  TripCreationService

Example: trip created
  event: trip.created
  tripId: trip_123
  destination: Paris

Common mistakes

Changing event payload shape without updating the spec.
Treating a consumer spec as permission to edit the producer.
Omitting required identifiers such as event ID or entity ID.
Mixing several unrelated events in one spec.
Hiding compatibility changes in implementation.

How to verify the result

The event spec is useful when:

event name and payload are clear
producer and consumer context is explicit
compatibility expectations are visible
examples clarify payload shape
review can detect unauthorized event changes

Language reference

← Write specs by level guides