Designing events analysts can join without rage-clicking

Analytics engineers rarely complain about JSON prettiness; they complain when two events claim to mean “purchase” but carry different grains. One fires per checkout session, another per line item. Joins become creative fiction.

Before emitting a new event, write the grain in one sentence: “One row per ___ occurring at ___ time, keyed by ___.” If you cannot finish the blanks, pause. Add stable identifiers that survive retries, and version the schema when you intentionally break compatibility.

We also recommend a lightweight contract file in-repo—no fancy platform required. Engineers and analysts comment on the same pull request. It feels slow for a week, then it removes month-long reconciliation projects. Our Warehouse Introduction for App Devs course practices this with a fictional subscription product so the mistakes are memorable, not expensive.