Skip to content

Systems and records

Event log data dictionary example: what each event type must explain

By SourceX Editorial · Updated

10 sections

Short answer

An event log data dictionary should have one row per event type, not per column, and each row should explain two things. The business meaning: what happened, to which case and objects, by which role, leaving which state. The system behavior: what writes the row, what its timestamp measures, whether retries or backfills repeat it and how long history survives. Add each event's known source limitation and a total to reconcile against.

Record timeline

Event log data dictionary

This page covers event log data dictionary example: what each event type must explain.Illustrative

Key takeaways

  • Document event types, not just columns: one status column can carry five different business events.
  • Every row needs a business half (meaning, case, actor role, resulting state) and a system half (writer, clock, repeats, retention).
  • Name the source limitation per event type so a reader knows which cases cannot be rebuilt with confidence.
  • Ship validator checks with the dictionary so anyone can confirm the log matches what it promises.
  • Version the dictionary and record what change in a source system would make a row wrong.

What should an event log data dictionary explain for each event type?

It should explain what the event means to the business and how the system came to write it. A reader who has never opened your CRM or help desk should be able to tell, from the dictionary alone, which real-world occurrence a row stands for, which case it belongs to, what state the case is in afterwards and how far to trust the timestamp.

That makes the event dictionary a different document from the field dictionary most teams already have. A field dictionary describes the column called status. An event dictionary describes the five or six things that happen when status changes, and says which of them the business cares about.

The filled example below covers an illustrative order-to-support workflow. Use its columns as is; replace its rows with your own event types, and keep the source limitation column even when the honest entry is unknown.

Why a column-by-column dictionary misses what an event log needs

An event log is a record of occurrences, and the meaning lives in the occurrence, not the column. The process mining standard IEEE 1849, known as XES, is built around traces: the XES definition describes each trace as the execution of one case of the logged process, holding the events observed during it, so the unit someone downstream reasons about is a case built from typed events. A field dictionary cannot tell them that a status change from Open to Pending was an agent waiting on the customer while Pending to Open was the customer replying.

Real workflows also touch several objects at once. The OCEL 2.0 specification for object-centric logs links one event to many objects and adds qualifiers that name the role each object plays, such as the order an invoice settles or the item a shipment carries. Your dictionary needs the same idea in plain language: for every event type, which objects it touches and in what role.

Finally, a column definition says nothing about behavior over time. It cannot say that a webhook may arrive twice, that a history table forgets old changes or that a timestamp records when a batch job ran rather than when a customer acted. Those behaviors decide whether a reconstructed case is true, so they belong next to the event they affect.

The business meaning half: activity, objects, actor role and resulting state

Each event type needs a short business definition that a workflow owner has approved. Write it as the occurrence, in the past tense and in the business's words, then add the fields below. If two people in the same team define an event differently, record both and mark the row unresolved; that is a finding, not a typo.

At a glance

The business meaning half: activity, objects, actor role and resulting state

Write states as a closed list per case type, and say which states are terminal. A reader who knows that Solved can be reopened but Closed cannot will treat the two very differently when deciding whether a case is complete.

  • Activity name: the business name for the occurrence, such as Refund approved, distinct from the system label that produced it.
  • Case notion: which object's lifecycle the event belongs to (order, ticket, claim) and the identifier used to join it.
  • Other objects and roles: every other object the event touches and what role it plays, for example the customer as requester and the agent as assignee.
  • Actor role: the kind of person or process that triggers it (customer, agent, approver, automation rule, integration user), never a named individual.
  • State before and after: the business state the case must be in for the event to be valid, and the state it leaves behind.
  • Business definition owner: the team that can confirm or change the definition, with the date it was confirmed.

The system behavior half: what writes the row and what its clock measures

For each event type, record the mechanism that writes the row, what the timestamp means and how the source can repeat, reorder or lose it. These behaviors differ by system, and they are documented by the vendors themselves.

Event specifications show the minimum to state. CloudEvents treats the source plus the id as the identity of a distinct event and allows a re-sent duplicate to carry the same id; its time attribute is when the occurrence happened, and a producer that cannot know that may use another time as long as it does so consistently for that source. Your dictionary should say which of those your source does.

Vendor documentation then fills in the specifics. The table lists four common sources and the behavior each one forces you to write down.

Do not copy the vendor's event name into the business meaning column. A Stripe event type or a Jira transition name describes what the software did; the dictionary row explains what that meant for the order or the ticket, and the two can diverge when a rule, an integration user or a bulk edit triggers the same system event.

The system behavior half: what writes the row and what its clock measures
SourceWhere event history comes fromBehavior to record in the dictionaryLimitation to name
StripeEvent objects delivered to webhook endpoints and listed through the Events APIEvents can arrive in a different order than they were generated, and an endpoint can receive the same event more than onceThe created timestamp is in seconds, so distinct events can share it and it should not set order alone
Jira CloudIssue changelogs returned by the REST changelog endpoint, oldest first, in pagesRecord which fields the changelog covers and that entries arrive per issue in date orderUse the dedicated changelog endpoint, which returns every changelog in pages, rather than a changelog embedded in an issue request
Zendesk SupportTicket audits, a read-only history in which one audit can hold several eventsOne customer-visible update can produce a comment, a status change and a notification togetherThe list-all audits endpoint is not meant for change capture; the incremental ticket event export is
SalesforceField history tracking on objects where it was switched on for chosen fieldsOnly tracked fields create history; changes to untracked fields leave no eventWithout Field Audit Trail, history is kept for up to 18 months, or 24 months through the API

A filled event dictionary for an order-to-support workflow (illustrative)

This is the asset: a filled event dictionary with source limitations for a made-up company that sells through Stripe, ships orders, and handles problems in Zendesk with escalations to Jira. The rows are illustrative, not drawn from any customer's systems. Copy the five columns; each row should fit on one screen.

Notice that two rows share one source column and that three rows carry a limitation severe enough to lower confidence in the cases that depend on them. That is normal. A dictionary with no limitations usually means nobody checked.

Read the rows in pairs. Payment succeeded and Order shipped together explain why some cases look out of order: one clock is precise and pushed in real time, the other is a nightly batch. Ticket waiting on customer and Ticket solved together explain why one ticket can have several waiting periods and more than one solve. A reviewer who reads the dictionary this way learns which durations they can measure and which they should only bound.

A filled event dictionary for an order-to-support workflow (illustrative)
Event typeBusiness meaning and resulting stateCase and other objectsSystem behavior and clockSource limitation
Order placedCustomer committed to buy; order moves to Awaiting paymentCase: order. Objects: customer as buyer, line items as contentsWritten by the storefront on checkout; time is the server clock in UTCAbandoned carts never create this event, so drop-off before checkout is invisible
Payment succeededFunds captured for the order; order moves to PaidCase: order, joined through the payment's metadata order ID. Objects: paymentStripe webhook; may arrive more than once and out of order; created time in secondsOrders without the metadata order ID cannot be joined and are counted as unlinked
Order shippedGoods left the warehouse; order moves to ShippedCase: order. Objects: shipment as carrier of listed itemsNightly batch import from the warehouse system; time is the batch run, not the scanTrue ship time is unknown to within a day; durations involving it are approximate
Ticket openedCustomer reported a problem; ticket moves to NewCase: ticket, linked to an order when the agent fills the order field. Objects: requesterFirst Zendesk audit on the ticket; time is the audit created timeTickets opened by email before the order field existed carry no order link
Ticket waiting on customerAgent asked the customer for information; ticket moves to PendingCase: ticket. Objects: assignee as actorStatus change event inside a Zendesk audit that may also contain a public commentAutomation rules can set Pending too; the actor field separates people from rules
Escalated to engineeringSupport handed the problem to engineering; ticket stays Open, issue moves to To doCase: ticket and issue, linked by the issue key stored on the ticketJira issue created by an integration user; time is the Jira server clockEscalations made by copying text by hand have no key and cannot be linked
Fix releasedEngineering resolved the cause; issue moves to DoneCase: issue. Objects: release versionStatus transition in the Jira changelog with author and timestampTeams that close issues in bulk at release time compress real fix times
Ticket solvedSupport considered the problem resolved; ticket moves to SolvedCase: ticket. Objects: assigneeStatus change event in a Zendesk audit; can be reopened by a customer replySolved is not resolved for the customer; reopen events must be kept, not deduplicated

How do you fill the dictionary from your own systems in one pass?

Start from the log, not from memory. Pull the distinct event type labels and their counts for the extraction window, sort them by count, and create one draft row per label before anyone writes a definition. Labels that nobody can explain go to the bottom with an open question, and they stay in the dictionary until someone answers it.

Then work in two short sessions with different people. In the first, a workflow owner fills the business half for each row: what happened, the case it belongs to, the state before and after, and who triggers it. In the second, the engineer who built or maintains the extraction fills the system half: the table or endpoint the row comes from, whether it is pushed or pulled, what the timestamp records, how retries show up and which history setting limits it. Keeping the sessions separate stops the engineer from inventing business meanings and the owner from guessing at clocks.

Finish by sampling. For each event type, pull a handful of real cases, read them end to end against the dictionary, and note every place where the story the log tells disagrees with what the owner says happened. Each disagreement becomes either a corrected definition or a new source limitation. The sample size is yours to set; what matters is that every event type is read at least once by someone who knows the work.

Which validator checks prove the log matches the dictionary?

Run checks that a person outside the team can repeat from the delivered files and the dictionary alone. Each check should produce a count and a pass or fail against a threshold you set in advance and write into the dictionary's header, so nobody adjusts the bar after seeing the result.

At a glance

Which validator checks prove the log matches the dictionary

  • Coverage: every distinct event type label in the log maps to exactly one dictionary row, and every row appears in the log at least once or is marked unused.
  • Identity: the combination of source and event ID is unique once documented retries are removed; report how many duplicates were removed and by which rule.
  • Clock: every timestamp parses, carries an explicit offset or a documented zone, and falls inside the extraction window.
  • Transitions: each event's state before matches the case's state after its previous event; report the share of cases with an illegal transition.
  • Joins: every cross-object link in the dictionary resolves; count unlinked events per event type rather than dropping them.
  • Retention: the earliest event per source is later than that source's documented history limit, or the gap is declared.
  • Concurrency: cases with two events at the same timestamp are counted and the tie-breaking rule is stated.
  • Reconciliation: the count of cases reaching a terminal state matches the source system's own report for the same period, within a stated tolerance.
  • Confidence: each case gets a grade from the limitations of the events it uses, so weak cases can be filtered instead of hidden.

A valid record and a failing record, side by side

One worked pair shows what the checks look for. Both records below are illustrative payment events for the made-up company above; the failing one shows three common defects at once.

A valid record and a failing record, side by side
FieldValid recordFailing recordCheck that catches it
Event typePayment succeededpayment_intent.succeeded with no mapping rowCoverage
Source and event IDstripe, evt_A1 seen oncestripe, evt_A1 seen twice with different load timesIdentity, then the documented retry rule
Timestamp2026-03-04T15:20:11Z2026-03-04 15:20:11 with no offsetClock
Case linkOrder O-1043 found in the order tableOrder field blankJoins, counted as unlinked
Prior case stateAwaiting paymentShipped, so payment appears after shippingTransitions, then a review of the warehouse batch clock

Could clock drift, an identifier mismatch or a missing transition change the case?

Yes, and the dictionary is where you say how likely that is for each event type. Clock problems change order and durations. In the example, the shipped event carries the batch run time, so a payment that arrives late can look as though it followed shipping. A timestamp without an offset is worse, because the error is the size of a time zone. RFC 3339 gives one honest way to write a known UTC time whose local offset is unknown, the -00:00 offset, and the dictionary should say which convention each source uses.

Identifier mismatches change which events belong together. If an order number is reused across two storefronts, or a ticket links to the wrong order, the reconstructed case merges two journeys into one. Record the identifier's scope per event type and count the events whose links you could not confirm.

Missing transitions change the path. A history that only tracks some fields, or that expired after its retention window, leaves cases that seem to jump from New to Solved. Mark the affected event types and the period they cover, and grade those cases lower rather than inventing the missing step.

Retries and concurrent work are the last two traps. A retried webhook that slips past deduplication adds a second payment to a case that had one, and two agents working the same ticket at once produce interleaved events that look like rework. For each event type, say whether a repeat can be legitimate, which field tells a retry from a second action, and what rule breaks ties between events with the same timestamp. Reconstruction confidence for a case should be no higher than the weakest of these answers for the events it contains.

Versioning the dictionary and handing it to an outside reviewer

Give the dictionary a version number, an as-of date, the extraction window it describes and a change log, and store the validator results beside it. Re-issue it whenever an event schema, a clock, an identifier link, a retention setting or a business state definition changes, because each of those can make an existing row wrong without anyone touching the log.

Keep the dictionary free of personal data. Describe actor roles, not people, and use made-up values in examples. Whether records may be shared at all is a separate question from whether they are well documented, and a good dictionary does not settle it.

When a company licenses operational records for AI, this is the document a reviewer reads first. Preparing records is part of how SourceX licenses business data directly from companies, and a dictionary with honest limitations shortens that preparation. Event logs move only after the company has approved what is in scope and the terms, and signed the agreement.

Frequently asked questions

What is the difference between an event log data dictionary and a regular data dictionary?

A regular data dictionary has one row per field and defines its type, meaning and allowed values. An event log data dictionary has one row per event type and explains the business occurrence, the case it belongs to, the system behavior that writes it and its known limitations. Most event logs need both, linked by the event type label.

How many event types should the dictionary cover?

All of them that appear in the delivered log, including technical ones you plan to filter out, so a reader can see what was removed and why. Mark rarely used or irrelevant types as excluded with a reason instead of leaving them undocumented. A coverage check should fail if any label in the log has no row.

Should event names follow XES or OCEL conventions?

Use business names in the dictionary and add a column that maps each one to the attribute names of the format you export. XES suits logs built around a single case notion, while OCEL 2.0 is designed for events that touch several objects. The dictionary's meanings should not change when the export format does.

What counts as a source limitation in an event dictionary?

Anything about the source that stops a reader from rebuilding a case with full confidence: a timestamp that records a batch run, a retention limit, untracked fields, missing links or retries that look like new actions. State the limitation, the period it affects and how cases that depend on it are graded.

Who should approve the business meaning of each event?

The workflow owner for the process, such as the support operations lead for ticket events or the finance lead for payment events, should confirm each definition and its states. Data engineers own the system behavior half. Record both approvals with dates so a later reader knows whom to ask.

Sources

  • The CloudEvents specification treats source plus id as a distinct event's identity, lets a re-sent duplicate keep its id, and defines time as when the occurrence happened. Source
  • Stripe says events may be delivered out of the order they were generated, endpoints can receive an event more than once, and created timestamps are recorded in seconds. Source
  • The Jira Cloud changelog endpoint returns a paginated list of all changelogs for an issue, oldest first. Source
  • Zendesk ticket audits are a read-only history in which one audit can contain several events, and the list-all endpoint is not meant for change capture. Source
  • Salesforce field history is retained for up to 18 months, or 24 months through the API, unless Field Audit Trail is used. Source
  • RFC 3339 uses the -00:00 offset to say the UTC time is known but the local offset is not. Source
  • IEEE 1849 (XES) is the IEEE standard for event logs and event streams used in process mining. Source
  • The OCEL 2.0 specification links events to multiple objects and uses qualifiers to name each object's role. Source
  • The XES standard definition describes each trace as the execution of one specific instance, or case, of the logged process, containing the events observed during it. Source

See if your company qualifies

A short company assessment. No data uploads are needed.

See if your company qualifies