An event catalogue is the durable record of what each important event means.
It should allow someone outside the original project to answer four questions: what fact does this event claim, which system knows that fact occurred, what context is required to interpret it, and what conclusions would overreach the evidence?
Template and example
Event catalogue template
The filled example defines quote acceptance as a persisted state transition, including retries, reversals, identifiers, minimisation and the limits of what the event can prove.
Blank template
Event catalogue item
Define one durable event claim, its recording rule, required context and limits of interpretation.
1. Event identity and claim
[domain.object_action]
Name the observed fact, not the interface control or hoped-for outcome.
[What observable activity or state change the event records]
[Related workflow and meaningful step]
[Who or what acted, what changed, and what one record represents]
Do not assume a person is always the right unit.
2. Recording rule
[System or service that knows the condition occurred]
[Exact observable condition that creates one event record]
Prefer a persisted state change when the event claims a committed outcome.
- [Attempt or interface action that does not meet the condition]
- [Duplicate, retry or replay that must not create another fact]
- [Reversal, cancellation or excluded state]
[How versions, retries, reversals, event time and ingestion time are handled]
3. Identifiers and properties
-
[object_id] -
[parent_workflow_id] -
[actor or account identifier only where needed]
-
[property_name: purpose and allowed values] -
[property_name: purpose and allowed values]
-
[property collected only for a defined question]
[Data deliberately excluded, access expectations and retention constraints]
Do not collect message text, contact details or sensitive attributes merely because they are available.
4. Measurement use and limits
- [Metric this event contributes to]
- [Diagnostic or health measure]
- [Question this event helps answer]
- [Question requiring other evidence]
[Limit of interpretation]
5. Ownership and review
[Person, role or team maintaining the durable event definition]
[Person, role or team responsible for reliable production]
- [Workflow, state model or source-system change]
- [Property, identifier or metric dependency change]
- [Confidence, privacy or data-quality concern]
Filled example
Event catalogue item: quote.accepted
This example defines quote acceptance as a persisted marketplace state change without claiming that service work was completed.
1. Event identity and claim
quote.accepted
The event names the state that the platform can observe directly.
The marketplace persisted that a customer accepted one valid quote for an eligible service request.
Request, compare and accept service quotes — accept a suitable quote.
The customer acts on one quote. One event record represents one persisted quote-acceptance transition linked to one service request.
2. Recording rule
The marketplace service that owns the quote and request state, emitted after the acceptance transaction succeeds.
A valid quote changes from an accept-able state to accepted, the related request is updated, and the transaction is committed.
The event must not fire from the button click alone.
- The customer opens the acceptance confirmation or selects the button but the transaction fails.
- The quote is already accepted and the client retries the request.
- An administrator views or edits the record without creating the accepted state.
- The accepted quote is later cancelled; that reversal requires a separate state-change event.
Emit once per successful quote-acceptance transition using the transaction or state-change identifier for deduplication. Preserve the time the state changed separately from ingestion time. Record later cancellation or reversal as a new event rather than deleting the original fact.
3. Identifiers and properties
-
request_id -
quote_id -
provider_account_id -
customer_account_id -
acceptance_change_id
-
quote_version: accepted version number -
service_type: controlled service category -
request_age_days: age at acceptance -
valid_quote_count: valid comparison set at acceptance -
workflow_version: marketplace workflow version
-
acceptance_route: comparison, message thread or quote detail -
required_site_visit: controlled boolean where operationally defined
Do not include names, addresses, telephone numbers, message text, free-text quote content or detailed service records. Limit access to pseudonymous identifiers and documented measurement properties; retain them only for the agreed analytical period.
4. Measurement use and limits
- 30-day request acceptance rate
- Time from request publication to acceptance
- Acceptance by valid quote count or workflow version
- Acceptance-event completeness and duplication checks
- Which eligible requests reach a recorded digital agreement?
- How long does acceptance take for mature request cohorts?
- How does acceptance vary by service type, quote choice or workflow version?
- Did accepted work proceed and deliver value? That requires downstream operational and customer evidence.
It does not prove that work was scheduled, completed, paid for, independently verified or satisfactory to the customer.
5. Ownership and review
Marketplace product and analytics representatives maintaining the acceptance definition and metric use.
Engineering team responsible for the quote-state service and analytics event delivery.
- Quote, request or cancellation state-model changes.
- A new acceptance route, transaction service or replay process.
- Changes to required identifiers, analytical retention or the 30-day acceptance metric.
- Duplicate, missing, late or disputed acceptance records.
A catalogue owns meaning, not delivery scope
The event catalogue should remain useful across releases. It owns the stable definition of an event and its relationship to measurement.
An instrumentation specification has a narrower job. It describes a particular implementation or change: which service will emit the event, what work is required, how migration or rollout will happen, and which tests must pass before release.
| Event catalogue | Instrumentation specification |
|---|---|
| Durable definition | Delivery-specific contract |
| What the event claims | What this implementation must do |
| Stable fire and non-fire rules | Source, schema, rollout and acceptance tests |
| Required interpretation context | Technical handling of retries, latency and environments |
| Definition and implementation ownership | Delivery owner, reviewers and release status |
The specification should reference the catalogue entry. It should not silently redefine the event inside a ticket.
Define the observed fact before the event name
Names improve readability, but the plain-language claim does the real work.
quote.accepted could mean:
- the customer selected an accept button;
- an API request was sent;
- the quote record changed state;
- the related service request was closed;
- an administrator marked the quote as accepted.
Those are different facts. The catalogue entry should choose one and make the source of truth visible.
Where the metric claims a committed outcome, prefer an event emitted from the persisted state change rather than the interface attempt. A button click can still be useful diagnostic evidence, but it should not stand in for a successful transaction.
Do not require personal identifiers by default
A weak event template often lists user_id, session_id and many properties before the question is known. That turns convenience into a collection policy.
Start with the objects and relationships required by the measurement. A marketplace acceptance event may need request_id, quote_id and a provider or customer account identifier. Another event may need no person-level identifier at all.
For every property, be able to answer:
- which question or calculation needs it;
- which controlled values are allowed;
- who can access it;
- how long it is retained;
- whether a less identifying alternative would work;
- what happens when it is missing or invalid.
Do not copy message text, addresses, telephone numbers or free-form service details into analytics events merely because the product already stores them elsewhere.
Record repetition and reversal honestly
Many events are not one-off milestones. Quotes can be revised, requests can be withdrawn, accepted work can be cancelled, and clients can retry a transaction.
The catalogue should state:
- whether the event may occur once or several times per object;
- how versions are represented;
- how duplicate delivery is detected;
- whether a reversal creates a separate event;
- which timestamp represents the business event;
- how late or replayed records should be interpreted.
Deleting the original fact after a reversal usually destroys useful history. Preserve the state transition and record the later change separately, unless the underlying data policy requires another approach.
Include what the event does not prove
A catalogue entry is incomplete without an interpretation boundary.
For example, quote.accepted supports a claim that the platform recorded a digital agreement. It does not prove that:
- work was scheduled;
- work was completed;
- payment happened;
- the customer was satisfied;
- the provider delivered acceptable quality;
- no off-platform agreement existed.
Writing this down protects the event from being reused as a stronger outcome measure months later.
Review by dependency and change
Review an event definition when:
- its workflow or state model changes;
- the authoritative source changes;
- identifiers, properties or allowed values change;
- retry, reversal or timestamp behaviour changes;
- an important metric or dashboard begins to depend on it;
- privacy, access or retention expectations change;
- duplicates, gaps, latency or unexplained breaks reduce confidence;
- the event should be consolidated or retired.
Implementation status is not a measure of event quality. A live event can still be ambiguous, incomplete or unsafe to use.
The catalogue is doing its job when teams can trace a metric to an event, trace the event to a defensible fact, and recognise where further evidence is needed.