A minimum reviewable record
The structure below is an illustrative work-note example, not a real company standard. For every event, the dictionary should answer 6 questions: business meaning, firing condition, required fields, user identity, effective version, and owner.
| Item | Example |
|---|---|
| Event | checkout_started |
| Trigger | The checkout page opens and initialises successfully |
| Required fields | product_id, source, client_version |
| Identity | User ID when signed in; device ID while anonymous |
Keep meaning stable with the name
If a name first means a button click and later means a successful page load, its time series is no longer comparable. A changed business meaning needs a new version or event, not a silent edit to the description.
Place business language and implementation detail together. Product colleagues need to understand the action; engineering and analysis need to know when it fires.
Record allowed values and missing-value rules
A field type is insufficient. State whether a source field is free text or an enumeration, and whether a missing value means unknown or not applicable. Otherwise one concept accumulates casing, abbreviations, and empty strings.
- List allowed and default values.
- State the clients and versions where the field is available.
- Mark sensitive fields and retention requirements.
- Record the deduplication key and duplicate-event handling.
Connect documentation to data with acceptance examples
Before release, prepare an action path and the events and fields expected at each point. During acceptance, compare the client log, the received raw record, and the analysis table. Agreement across all three shows that the written definition reached the data pipeline.
- Follow the pathComplete one defined flow and retain its time and test identity.
- Inspect raw eventsReview order, field values, duplicate records, and time zone.
- Inspect the analysis tableConfirm that cleaning, deduplication, and identity joins preserve the business meaning.
Treat changes as versioned work
The dictionary should retain the change date, affected scope, and migration note. Queries should also state the event versions they cover. When a time series breaks, this record separates behavior change from measurement change.